This README outlines the functionality of the Branch Metrics Web SDK, and how to easily incorporate it into a web app.
Live demo: https://cdn.branch.io/example.html
The Branch Web SDK provides an easy way to interact with the Branch API on your website or web app. It requires no frameworks, and is only ~7K gzipped.
To use the Web 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
.
Once initialized, the Branch Web SDK allows you to create and share links with a banner, over SMS, or your own methods. It also offers event tracking, access to referrals, and management of credits.
This SDK requires native browser Javascript and has been tested in all modern browsers with sessionStorage capability. No 3rd party libraries are needed to make use of the SDK as is it 100% native Javascript.
Chrome | Firefox | Safari | IE |
---|---|---|---|
✔ | ✔ | ✔ | 9, 10, 11 |
You will need to create a Branch Metrics app to obtain your Branch Key (you will have the option to toggle between live and test modes).
Be sure to replace BRANCH KEY
with your actual Branch Key found in your account dashboard.
Formerly App ID Note that for the time being, initializing the Web SDK with an App ID will still work, it is strongly recomended you switch to using your live and test API keys.
<script type="text/javascript">
(function(b,r,a,n,c,h,_,s,d,k){if(!b[n]||!b[n]._q){for(;s<_.length;)c(h,_[s++]);d=r.createElement(a);d.async=1;d.src="https://cdn.branch.io/branch-v1.4.0.min.js";k=r.getElementsByTagName(a)[0];k.parentNode.insertBefore(d,k);b[n]=h}})(window,document,"script","branch",function(b,r){b[r]=function(){b._q.push([r,arguments])}},{_q:[],_v:1},"init data setIdentity logout track link sendSMS referrals credits redeem banner closeBanner".split(" "),0);
branch.init('BRANCH KEY', function(err, data) {
// callback to handle err or data
});
</script>
If you use Bower or npm, you can run bower install branch-sdk
or npm install branch-sdk
respectively to get the SDK.
In addition to working as a standalone library, the Branch SDK works great in CommonJS environments (browserify, webpack) as well as RequireJS environments (RequireJS/AMD). Just require('branch')
or define(['branch'], function(branch) { ... });
to get started!
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/Web-SDK.git. For example:
cordova plugin add https://github.com/BranchMetrics/Web-SDK.git
For a full walktrough specific to integrating the Web SDK with a Cordova app, see the Cordova Guide.
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.
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);
});
The session close will be sent automatically on any ‘pause’ event.
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 immidiatley 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 gauranteed 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(...);
- Branch Session
- Event Tracking Methods
-
Deeplinking Methods
-
Referral Methods
-
Smart Banner
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!!!
THIS METHOD IS CURRENTLY ONLY AVAILABLE IN THE CORDOVA/PHONEGAP PLUGIN
Parameters
branch_key: string
, required - Your Branch live key, or (depreciated) your app id.
options: Object
, optional - options: 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
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.
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.
branch.init(
branch_key,
callback (err, data),
is_referrable
);
callback(
"Error message",
{
data: { }, // 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
}
);
Note: Branch.init
must be called prior to calling any other Branch functions.
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.
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.
THIS METHOD IS CURRENTLY ONLY AVAILABLE IN THE CORDOVA/PHONEGAP PLUGIN
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.
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.
branch.setIdentity(
identity,
callback (err, data)
);
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: { }, // Returns the initial referring data for this identity, if exists.
referring_identity: '12345' // Returns the initial referring identity for this identity, if exists.
}
);
Parameters
callback: function
, optional
Logs out the current session, replaces session IDs and identity IDs.
branch.logout(
callback (err)
);
callback(
"Error message"
);
Parameters
callback: function
, optional
Close the current session.
branch.close(
callback (err)
);
callback(
"Error message"
);
THIS METHOD IS CURRENTLY ONLY AVAILABLE IN THE CORDOVA/PHONEGAP PLUGIN
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.
branch.event(
event,
metadata,
callback (err)
);
callback("Error message");
Parameters
linkData: Object
, required - link data and metadata.
callback: function
, required - returns a string of the Branch deep linking URL.
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.
branch.link(
linkData,
callback (err, link)
);
branch.link({
tags: [ 'tag1', 'tag2' ],
channel: 'facebook',
feature: 'dashboard',
stage: 'new user',
type: 1,
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(
"Error message",
'https://bnc.lt/l/3HZMytU-BW' // Branch deep linking URL
);
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
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.
branch.sendSMS(
phone,
linkData,
options,
callback (err, data)
);
branch.sendSMS(
phone: '9999999999',
{
tags: ['tag1', 'tag2'],
channel: 'facebook',
feature: 'dashboard',
stage: 'new user',
type: 1,
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("Error message");
THIS METHOD IS CURRENTLY ONLY AVAILABLE IN THE WEB SDK NOT THE CORDOVA/PHONEGAP PLUGIN
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:
- Reward the original user for taking action (eg. inviting, purchasing, etc)
- Reward the invitee for installing the app from the original user's referral link
- 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.
Parameters
callback: function
, required - returns an object with referral data.
Retrieves a complete summary of the referrals the current user has made.
branch.referrals(
callback (err, data)
);
callback(
"Error message",
{
'install': {
total: 5,
unique: 2
},
'open': {
total: 4,
unique: 3
},
'buy': {
total: 7,
unique: 3
}
}
);
Parameters
data: 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 data can containt the following fields: "amount" - A required integer specifying the number of credits added when the code is applied. "bucket" - The optional bucket to apply the credits to. Defaults to "default". "calculation_type" - A required integer. 1 for unlimited uses, 0 for one use. "location" - A required integer. Determines who get's the credits. 0 for the referree, 2 for the referring user or 3 for both. "prefix" - An optional string to be prepended to the code. "expiration" - An optional date string. If present, determines the date on which the code expires.
branch.getCode( data, callback(err,data) );
branch.getCode(
{
"amount":10,
"bucket":"party",
"calculation_type":1,
"location":2
}
callback (err, data)
);
callback(
"Error message",
{
"referral_code":"AB12CD"
}
);
THIS METHOD IS CURRENTLY ONLY AVAILABLE IN THE CORDOVA/PHONEGAP PLUGIN
Parameters
code: string
, required - the code string to validate.
callback: function
, optional - returns an error if unsuccessful
Validate a referral code before using.
branch.validateCode(
code, // The code to validate
callback (err)
);
branch.validateCode(
"AB12CD",
function(err) {
if (err) {
console.log(err);
} else {
console.log("Code is valid");
}
}
);
callback(
"Error message",
callback(err)
);
THIS METHOD IS CURRENTLY ONLY AVAILABLE IN THE CORDOVA/PHONEGAP PLUGIN
Parameters
code: string
, required - the code string to apply.
callback: function
, optional - returns an error if unsuccessful
Apply a referral code.
branch.applyCode(
code, // The code to apply
callback (err)
);
branch.applyCode(
"AB12CD",
function(err) {
if (err) {
console.log(err);
} else {
console.log("Code applied");
}
}
);
callback(
"Error message",
callback(err)
);
THIS METHOD IS CURRENTLY ONLY AVAILABLE IN THE CORDOVA/PHONEGAP PLUGIN
Parameters
callback: function
, required - returns an object with credit data.
This call will retrieve the entire history of credits and redemptions from the individual user.
branch.credits(
callback (err, data)
);
callback(
"Error message",
{
'default': 15,
'other bucket': 9
}
);
Parameters
data: 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.
branch.creditHistory(
data,
callback(err, data)
);
##### Example
```js
branch.creditHistory(
{
"length":50,
"direction":0,
"begin_after_id:"123456789012345",
"bucket":"default"
}
callback (err, data)
);
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"
}
]
);
THIS METHOD IS CURRENTLY ONLY AVAILABLE IN THE CORDOVA/PHONEGAP PLUGIN
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
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)
);
branch.redeem(
5,
"Rubies",
function(err) {
console.log(err);
}
);
callback("Error message");
The Branch Web SDK has a built in sharing banner, that automatically displays a device specific banner for desktop, iOS, and Android. If the banner is shown on a desktop, a form for sending yourself the download link via SMS is shown. Otherwise, a button is shown that either says an "open" app phrase, or a "download" app phrase, based on whether or not the user has the app installed. Both of these phrases can be specified in the parameters when calling the banner function. Styling: The banner automatically styles itself based on if it is being shown on the desktop, iOS, or Android.
Parameters
options: Object
, required - object of all the options to setup the banner
linkData: Object
, required - object of all link data, same as Branch.link()
Display a smart banner directing the user to your app through a Branch referral link. The linkData
param is the exact same as in branch.link()
.
iOS Smart Banner | Android Smart Banner | Desktop Smart Banner |
---|---|---|
THIS METHOD IS ONLY AVAILABLE IN THE WEB SDK NOT IN THE CORDOVA/PHONEGAP PLUGIN
branch.banner(
options, // Banner options: See example for all available options
linkData // Data for link, same as Branch.link()
);
branch.banner({
icon: 'http://icons.iconarchive.com/icons/wineass/ios7-redesign/512/Appstore-icon.png',
title: 'Branch Demo App',
description: 'The Branch demo app!',
openAppButtonText: 'Open', // Text to show on button if the user has the app installed
downloadAppButtonText: 'Download', // Text to show on button if the user does not have the app installed
iframe: true, // Show banner in an iframe, recomended to isolate Branch banner CSS
showiOS: true, // Should the banner be shown on iOS devices?
showAndroid: true, // Should the banner be shown on Android devices?
showDesktop: true, // Should the banner be shown on desktop devices?
disableHide: false, // Should the user have the ability to hide the banner? (show's X on left side)
forgetHide: false, // Should we remember or forget whether the user hid the banner?
make_new_link: false // Should the banner create a new link, even if a link already exists?
}, {
phone: '9999999999',
tags: ['tag1', 'tag2'],
feature: 'dashboard',
stage: 'new user',
type: 1,
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'
}
});
The App Banner includes a close button the user can click, but you may want to close the banner with a timeout, or via some
other user interaction with your web app. In this case, closing the banner is very simple by calling Branch.closeBanner()
.
branch.closeBanner();
Feel free to report any bugs you might encounter in the repo's issues. Any support inquiries outside of bugs please send to [email protected].