branch-sdk-imagitas v1.6.36

Full Documentation for Cordova SDK

New documentation portal and support portal with user forums

This documentation outlines the functionality of the Branch Metrics Cordova SDK, and how to easily incorporate it into a Cordova app. The Cordova SDK shares the same code base as the Branch Web SDK, and includes functions to call all of the same API endpoints.

Live demo of the Web SDK: https://cdn.branch.io/example.html

To use the Cordova SDK, you'll need to first initialize it with your Branch Key found in your Branch dashboard. You'll also need to register when your users login with setIdentity, and when they logout with logout.

Register you app

You can sign up for your own Branch Key at https://dashboard.branch.io

Quick Install of Cordova/Phonegap SDK

This Web SDK can also be used for Cordova/Phonegap applications. It is provided as a plugin and can be installed with Cordova plugin or the Plugman tool. Point the tool at this repositry, https://github.com/BranchMetrics/Cordova-Ionic-PhoneGap-Deferred-Deep-Linking-SDK. For example:

cordova plugin add https://github.com/BranchMetrics/Cordova-Ionic-PhoneGap-Deferred-Deep-Linking-SDK

Note that this SDK is meant for use with full Cordova/PhoneGap apps. If you are building a hybrid app using an embedded web view and you want to access the Branch API from native code you will want to use the platform specific SDKs and pass data into Javascript if needed.

Running Cordova Testbed App

This repo includes a sample app, that demonstrates all of the available methods in the Branch Cordova SDK. Building this app is very simple:

Switch to the Cordova dir

$ cd cordova-testbed

Run the init script to install all the required plugins

$ ./init.sh

Build the Cordova app and launch in the iOS emulator

$ cordova emulate ios

Initialization and Event Handling

You should initialize the Branch SDK session once the ‘deviceready’ event fires and each time the ‘resume’ event fires. See the example code below. You will need your Branch Key from the Branch dashboard.

  branch.init("YOUR BRANCH KEY HERE", function(err, data) {
  	app.initComplete(err, data);
  });

Formerly getInstance() and initSession()

Here is the location of the Branch Key that you will need for the branch.init call above (formerly app id, which is now depreciated):

The session close will be sent automatically on any ‘pause’ event.

Register an activity for direct deep linking (optional but recommended)

In your project's manifest file, you can register your app to respond to direct deep links (yourapp:// in a mobile browser) by adding the second intent filter block. Also, make sure to change yourapp to a unique string that represents your app name.

Secondly, make sure that this activity is launched as a singleTask. This is important to handle proper deep linking from other apps like Facebook.

Typically, you would register some sort of splash activity that handles routing for your app.

<activity
	android:name="com.yourapp.SplashActivity"
	android:label="@string/app_name"
	<!-- Make sure the activity is launched as "singleTask" -->
	android:launchMode="singleTask"
	 >
	<intent-filter>
		<action android:name="android.intent.action.MAIN" />
		<category android:name="android.intent.category.LAUNCHER" />
	</intent-filter>

	<!-- Add this intent filter below, and change yourapp to your app name -->
	<intent-filter>
		<data android:scheme="yourapp" android:host="open" />
		<action android:name="android.intent.action.VIEW" />
		<category android:name="android.intent.category.DEFAULT" />
		<category android:name="android.intent.category.BROWSABLE" />
	</intent-filter>
</activity>

iOS plist

Add your Branch Key to your project

After you register your app, your Branch Key can be retrieved on the Settings page of the dashboard. Now you need to add it to YourProject-Info.plist (Info.plist for Swift).

1. In plist file, mouse hover "Information Property List" which is the root item under the Key column.
2. After about half a second, you will see a "+" sign appear. Click it.
3. In the newly added row, fill in "branch_key" for its key, leave type as String, and enter your app's Branch Key obtained in above steps in the value column.
4. Save the plist file.

Register a URI scheme direct deep linking (optional but recommended)

You can register your app to respond to direct deep links (yourapp:// in a mobile browser) by adding a URI scheme in the YourProject-Info.plist file. Make sure to change yourapp to a unique string that represents your app name.

1. In Xcode, click on YourProject-Info.plist on the left.
2. Find URL Types and click the right arrow. (If it doesn't exist, right click anywhere and choose Add Row. Scroll down and choose URL Types)
3. Add "yourapp", where yourapp is a unique string for your app, as an item in URL Schemes as below:

Alternatively, you can add the URI scheme in your project's Info page.

1. In XCode, click your project in the Navigator (on the left side).
2. Select the "Info" tab.
3. Expand the "URL Types" section at the bottom.
4. Click the "+" sign to add a new URI Scheme, as below:

SDK Method Queue

Initializing the SDK is an asynchronous method with a callback, so it may seem as though you would need to place any method calls that will execute immediately inside the branch.init() callback. We've made it even easier than that, by building in a queue to the SDK! The only thing that is required is that branch.init() is called prior to any other methods. All SDK methods called are guaranteed to: 1. be executed in the order that they were called, and 2. wait to execute until the previous SDK method finishes. Therefore, it is 100% allowable to do something like:

branch.init(...);
branch.banner(...);

If branch.init() fails, all subsequent branch methods will fail.

API Reference

1. Branch Session

• .init()
• .data()
• .first()
• .setIdentity()
• .logout()
• .close()

2. Event Tracking

• .track()

3. Deep Linking

• .link()
• .sendSMS()

4. Referrals and Credits

• .referrals()
• .getCode()
• .validateCode()
• .applyCode()
• .credits()
• .creditHistory()
• .redeem()

setDebug(debug)

Parameters

debug: boolean, required - Set the SDK debug flag.

Setting the SDK debug flag will generate a new device ID each time the app is installed instead of possibly using the same device id. This is useful when testing.

This needs to be set before the Branch.init call!!!

init(branch_key, options, callback)

Parameters

branch_key: string, required - Your Branch live key, or (depreciated) your app id.

options: Object, optional - { isReferrable: Is this a referrable session }.

callback: function, optional - callback to read the session data.

THE "isReferrable" OPTION IS ONLY USED IN THE CORDOVA/PHONEGAP PLUGIN AND THE TITANIUM MODULE

Adding the Branch script to your page automatically creates a window.branch object with all the external methods described below. All calls made to Branch methods are stored in a queue, so even if the SDK is not fully instantiated, calls made to it will be queued in the order they were originally called. If the session was opened from a referring link, data() will also return the referring link click as referring_link, which gives you the ability to continue the click flow.

The init function on the Branch object initiates the Branch session and creates a new user session, if it doesn't already exist, in sessionStorage.

Useful Tip: The init function returns a data object where you can read the link the user was referred by.

Usage

branch.init(
    branch_key,
    options
    callback (err, data),
);

Callback Format

callback(
     "Error message",
     {
          data_parsed:        { },                          // If the user was referred from a link, and the link has associated data, the data is passed in here.
          referring_identity: '12345',                      // If the user was referred from a link, and the link was created by a user with an identity, that identity is here.
          has_app:            true,                         // Does the user have the app installed already?
          identity:           'BranchUser',                 // Unique string that identifies the user
          referring_link:          'https://bnc.lt/c/jgg75-Gjd3' // The referring link click, if available.
     }
);

Note: Branch.init must be called prior to calling any other Branch functions.

data(callback)

Parameters

callback: function, optional - callback to read the session data.

Returns the same session information and any referring data, as Branch.init, but does not require the app_id. This is meant to be called after Branch.init has been called if you need the session information at a later point. If the Branch session has already been initialized, the callback will return immediately, otherwise, it will return once Branch has been initialized.

first(callback)

Parameters

callback: function, optional - callback to read the session data.

Returns the same session information and any referring data, as Branch.init did when the app was first installed. This is meant to be called after Branch.init has been called if you need the first session information at a later point. If the Branch session has already been initialized, the callback will return immediately, otherwise, it will return once Branch has been initialized.

setIdentity(identity, callback)

Parameters

identity: string, required - a string uniquely identifying the user – often a user ID or email address.

callback: function, optional - callback that returns the user's Branch identity id and unique link.

Formerly identify()

Sets the identity of a user and returns the data. To use this function, pass a unique string that identifies the user - this could be an email address, UUID, Facebook ID, etc.

Usage

branch.setIdentity(
    identity,
    callback (err, data)
);

Callback Format

callback(
     "Error message",
     {
          identity_id:             '12345', // Server-generated ID of the user identity, stored in `sessionStorage`.
          link:                    'url',   // New link to use (replaces old stored link), stored in `sessionStorage`.
          referring_data_parsed:    { },      // Returns the initial referring data for this identity, if exists, as a parsed object.
          referring_identity:      '12345'  // Returns the initial referring identity for this identity, if exists.
     }
);

logout(callback)

Parameters

callback: function, optional

Logs out the current session, replaces session IDs and identity IDs.

Usage

branch.logout(
    callback (err)
);

Callback Format

callback(
     "Error message"
);

close(callback)

Parameters

callback: function, optional

Close the current session.

Usage

branch.close(
    callback (err)
);

Callback Format

callback(
     "Error message"
);

Tracking events

track(event, metadata, callback)

Parameters

event: string, required - name of the event to be tracked.

metadata: Object, optional - object of event metadata.

callback: function, optional

This function allows you to track any event with supporting metadata. Use the events you track to create funnels in the Branch dashboard. The metadata parameter is a formatted JSON object that can contain any data and has limitless hierarchy.

Usage

branch.track(
    event,
    metadata,
    callback (err)
);

Callback Format

callback("Error message");

Deeplinking Methods

Creating a deep linking link

link(data, callback)

Parameters

data: Object, required - link data and metadata.

callback: function, required - returns a string of the Branch deep linking URL.

Formerly createLink()

Creates and returns a deep linking URL. The data parameter can include an object with optional data you would like to store, including Facebook Open Graph data.

data The dictionary to embed with the link. Accessed as session or install parameters from the SDK.

Note You can customize the Facebook OG tags of each URL if you want to dynamically share content by using the following optional keys in the data dictionary. Please use this Facebook tool to debug your OG tags!

Also, you can set custom redirection by inserting the following optional keys in the dictionary:

You have the ability to control the direct deep linking of each link as well:

Usage

branch.link(
    data,
    callback (err, link)
);

Example

branch.link({
    tags: [ 'tag1', 'tag2' ],
    channel: 'facebook',
    feature: 'dashboard',
    stage: 'new user',
    data: {
        mydata: 'something',
        foo: 'bar',
        '$desktop_url': 'http://myappwebsite.com',
        '$ios_url': 'http://myappwebsite.com/ios',
        '$ipad_url': 'http://myappwebsite.com/ipad',
        '$android_url': 'http://myappwebsite.com/android',
        '$og_app_id': '12345',
        '$og_title': 'My App',
        '$og_description': 'My app\'s description.',
        '$og_image_url': 'http://myappwebsite.com/image.png'
    }
}, function(err, link) {
    console.log(err, link);
});

Callback Format

callback(
    "Error message",
    'https://bnc.lt/l/3HZMytU-BW' // Branch deep linking URL
);

sendSMS(phone, linkData, options, callback)

Parameters

phone: string, required - phone number to send SMS to

linkData: Object, required - object of link data

options: Object, optional - options: make_new_link, which forces the creation of a new link even if one already exists

callback: function, optional - Returns an error if unsuccessful

Formerly SMSLink()

A robust function to give your users the ability to share links via SMS. If the user navigated to this page via a Branch link, sendSMS will send that same link. Otherwise, it will create a new link with the data provided in the params argument. sendSMS also registers a click event with the channel pre-filled with 'sms' before sending an sms to the provided phone parameter. This way the entire link click event is recorded starting with the user sending an sms.

Note: sendSMS will automatically send a previously generated link click, along with the data object in the original link. Therefore, it is unneccessary for the data() method to be called to check for an already existing link. If a link already exists, sendSMS will simply ignore the data object passed to it, and send the existing link. If this behaivior is not desired, set make_new_link: true in the options object argument of sendSMS, and sendSMS will always make a new link.

Supports international SMS.

Usage

branch.sendSMS(
    phone,
    linkData,
    options,
    callback (err, data)
);

Example

branch.sendSMS(
    phone: '9999999999',
    {
        tags: ['tag1', 'tag2'],
        channel: 'facebook',
        feature: 'dashboard',
        stage: 'new user',
        data: {
            mydata: 'something',
            foo: 'bar',
            '$desktop_url': 'http://myappwebsite.com',
            '$ios_url': 'http://myappwebsite.com/ios',
            '$ipad_url': 'http://myappwebsite.com/ipad',
            '$android_url': 'http://myappwebsite.com/android',
            '$og_app_id': '12345',
            '$og_title': 'My App',
            '$og_description': 'My app\'s description.',
            '$og_image_url': 'http://myappwebsite.com/image.png'
        }
    },
    { make_new_link: true }, // Default: false. If set to true, sendSMS will generate a new link even if one already exists.
    function(err) { console.log(err); }
});

Callback Format

callback("Error message");

Referral system rewarding functionality

In a standard referral system, you have 2 parties: the original user and the invitee. Our system is flexible enough to handle rewards for all users for any actions. Here are a couple example scenarios: 1. Reward the original user for taking action (eg. inviting, purchasing, etc) 2. Reward the invitee for installing the app from the original user's referral link 3. Reward the original user when the invitee takes action (eg. give the original user credit when their the invitee buys something)

These reward definitions are created on the dashboard, under the 'Reward Rules' section in the 'Referrals' tab on the dashboard.

Warning: For a referral program, you should not use unique awards for custom events and redeem pre-identify call. This can allow users to cheat the system.

Retrieve referrals list

referrals(callback)

Parameters

callback: function, required - returns an object with referral data.

Formerly showReferrals()

Retrieves a complete summary of the referrals the current user has made.

Usage

branch.referrals(
    callback (err, data)
);

Callback Format

callback(
    "Error message",
    {
        'install': {
             total: 5,
             unique: 2
        },
        'open': {
             total: 4,
             unique: 3
        },
        'buy': {
            total: 7,
            unique: 3
        }
    }
);

Referral Codes

getCode(options, callback)

Parameters

options: Object, required - contins options for referral code creation.

callback: function, optional - returns an error if unsuccessful

Create a referral code using the supplied parameters. The code can be given to other users to enter. Applying the code will add credits to the referrer, referree or both. The options object can containt the following properties:

Usage

branch.getCode( options, callback(err,data) );

Example

branch.getCode(
    {
      "amount":10,
      "bucket":"party",
      "calculation_type":1,
      "location":2
    },
    callback (err, data)
);

Callback Format

callback(
     "Error message",
     {
       "referral_code":"AB12CD"
     }
);

validateCode(code, callback)

Parameters

code: string, required - the code string to validate.

callback: function, optional - returns an error if unsuccessful

Validate a referral code before using.

Usage

branch.validateCode(
    code, // The code to validate
    callback (err)
);

Example

branch.validateCode(
    "AB12CD",
    function(err) {
        if (err) {
            console.log(err);
        } else {
            console.log("Code is valid");
        }
    }
);

Callback Format

callback(
    "Error message",
    callback(err)
);

applyCode(code, callback)

Parameters

code: string, required - the code string to apply.

callback: function, optional - returns an error if unsuccessful

Apply a referral code.

Usage

branch.applyCode(
    code, // The code to apply
    callback (err)
);

Example

branch.applyCode(
    "AB12CD",
    function(err) {
        if (err) {
            console.log(err);
        } else {
            console.log("Code applied");
        }
    }
);

Callback Format

callback(
    "Error message",
    callback(err)
);

Credit Functions

credits(callback)

Parameters

callback: function, required - returns an object with credit data.

Formerly showCredits()

This call will retrieve the entire history of credits and redemptions from the individual user.

Usage

branch.credits(
    callback (err, data)
);

Callback Format

callback(
    "Error message",
    {
        'default': 15,
        'other bucket': 9
    }
);

creditHistory(options, callback)

Parameters

options: Object, optional - options controlling the returned history.

callback: function, required - returns an array with credit history data.

This call will retrieve the entire history of credits and redemptions from the individual user. Properties available in the options object:

Usage

branch.creditHistory(
     options,
     callback(err, data)
);

Example

branch.creditHistory(
    {
      "length":50,
      "direction":0,
      "begin_after_id":"123456789012345",
      "bucket":"default"
    }
    callback (err, data)
);

Callback Format

callback(
    "Error message",
[
    {
        "transaction": {
                           "date": "2014-10-14T01:54:40.425Z",
                           "id": "50388077461373184",
                           "bucket": "default",
                           "type": 0,
                           "amount": 5
                       },
        "referrer": "12345678",
        "referree": null
    },
    {
        "transaction": {
                           "date": "2014-10-14T01:55:09.474Z",
                           "id": "50388199301710081",
                           "bucket": "default",
                           "type": 2,
                           "amount": -3
                       },
        "referrer": null,
        "referree": "12345678"
    }
]
);

Credit redemption

redeem(amount, bucket, callback)

Parameters

amount: number, required - an amount (int) of number of credits to redeem

bucket: string, required - the name of the bucket (string) of which bucket to redeem the credits from

callback: function, optional - returns an error if unsuccessful

Formerly redeemCredits()

Credits are stored in buckets, which you can define as points, currency, whatever makes sense for your app. When you want to redeem credits, call this method with the number of points to be redeemed, and the bucket to redeem them from.

branch.redeem(
    amount, // Amount of credits to be redeemed
    bucket,  // String of bucket name to redeem credits from
    callback (err)
);

Example

branch.redeem(
    5,
    "Rubies",
    function(err) {
        console.log(err);
    }
);

Callback Format

callback("Error message");

Bugs / Help / Support

Feel free to report any bugs you might encounter in the repo's issues. Any support inquiries outside of bugs please send to support@branch.io.