init
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:
Be executed in the order that they were called in.
Wait to execute until the previous SDK method finishes.
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 Branch Web 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, the data()
function 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
.
Method | Description |
---|---|
| Initiate a Branch session. |
options
Data Object
Key | Value | Type | Required |
---|---|---|---|
| The current user's browser-fingerprint-id. |
| No |
| If you would like to test how Journeys render on your page before activating them, you can set the value of this parameter to the id of the view you are testing. |
| No |
| When |
| No |
| When |
| No |
| When |
| No |
| Value specifying the number of times a Branch API call can be retried. |
| No |
| Amount of time in milliseconds to wait before retrying a timed-out request to the Branch API. |
| No |
| Duration in milliseconds that the system should wait for a response before considering any Branch API call to have timed out. |
| No |
| Key-value pairs used to target Journeys users via the "is viewing a page with metadata key" filter. |
| No |
| A nonce value that will be added to |
| No |
| Setting to |
| No |
Example Usage
branch.init(
branch_key,
options,
callback (err, data),
);
Example Response
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, // Whether the user has 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
}
);
setRequestMetaData
Method | Description |
---|---|
| Add additional metadata in the form of key-value pairs to every network request that is made by the Branch Web SDK. |
Argument | Type | Description | Required |
---|---|---|---|
|
| Metadata key. | Yes |
|
| Metadata value. | Yes |
Example Usage
branch.setRequestMetadata("key","value");
setAPIUrl
Method | Description |
---|---|
| Sets a custom base URL for all calls to the Branch API. |
Argument | Type | Description | Required |
---|---|---|---|
|
| The base URL that the Branch API uses. | Yes |
Example Usage
branch.setAPIUrl("https://api2.myhost.io");
getAPIUrl
Method | Description |
---|---|
| Get the previously set custom base URL for all calls to the Branch API. |
Returns |
---|
The base URL for all calls to the Branch API. |
Example Usage
branch.getAPIUrl();
data
Method | Description |
---|---|
| Returns the same session information and any referring data as |
Argument | Type | Description | Required |
---|---|---|---|
|
| Callback to read the session data. | No |
Example Usage
branch.data(function(err, data) {
response.html(err || JSON.stringify(data));
});
first
Method | Description |
---|---|
| Returns the same session information and any referring data as |
Argument | Type | Description | Required |
---|---|---|---|
|
| Callback to read the session data. | No |
Example Usage
branch.first(function(err, data) {
response.html(err || JSON.stringify(data));
});
setIdentity
This method may be helpful if you have your own user IDs for customers, or you want referral and event data to persist across platforms or uninstall/reinstall. Using this method can make it easier to know when users access your service from different devices.
Sending PII
Be sure to not send any PII through the
setIdentity()
method. For additional details, please view our guide on Best Practices to Avoid Sending PII to Branch.
Method | Description |
---|---|
| Identifies the current user to the Branch API by supplying a unique identifier. |
Argument | Type | Description | Required |
---|---|---|---|
|
| A string uniquely identifying the user - often a user ID. | Yes |
|
| Callback that returns the user's Branch identity ID and unique link. | No |
Returns |
---|
Callback containing the user's Branch identity ID and unique link. |
Example Usage
branch.setIdentity(
"unique-user-aa11",
callback (err, data)
);
Example Response
callback(
"Error message",
{
randomized_bundle_token: '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
Method | Description |
---|---|
| Logs the user out of the Branch current session. |
Argument | Type | Description |
---|---|---|
|
| Callback that returns whether the session was successful. |
Example Usage
branch.logout(
callback (err)
);
Example Response
callback(
"Error message"
);
getBrowserFingerprintId
Method | Description |
---|---|
| Returns the current user's browser-fingerprint-id. |
Argument | Type | Description |
---|---|---|
|
| Callback to read a user's browser-fingerprint-id. |
Example Usage
branch.getBrowserFingerprintId(function(err, data) { console.log(data); });
Example Response
callback(
null,
'00000000000000000', // browser-fingerprint-id, stored in `localStorage`
);
lastAttributedTouchData
Method | Description |
---|---|
| Returns last attributed touch data for current user. |
Argument | Type | Description | Required |
---|---|---|---|
|
| The number of days to look up attribution data for. | Yes |
|
| Callback to read last attributed touch data. | No |
Example Usage
branch.lastAttributedTouchData(
attribution_window,
callback (err, data)
);
logEvent
By default, the Branch Web SDK tracks clicks, opens, installs, reinstalls, impressions, and Journeys dismissals automatically (out-of-the-box).
You can also track special user actions or application-specific events. For example, you can track when a user adds an item to a shopping cart or searches for a keyword.
Learn more about tracking Commerce, Content, Lifecycle, and Custom Events via the logEvent()
method in our guide.
Method | Description |
---|---|
| Log a Branch Event to Branch's servers for tracking and analytics. |
Argument | Type | Description | Required |
---|---|---|---|
|
| Name of the event. | Yes |
|
| Relevant information about the event. | No |
|
| Information about the items associated with the event. For example, products purchased (content items) during a transaction (event). | No |
|
| An alias for the event name, if applicable. | No |
|
| Callback that returns whether event logging was successful. | No |
Example Usage for Standard Events (Commerce, Content, and Lifecycle)
// Example for how to log a `PURCHASE` Commerce Event
var event_and_custom_data = {
"transaction_id": "tras_Id_1232343434",
"currency": "USD",
"revenue": 180.2,
"shipping": 10.5,
"tax": 13.5,
"coupon": "promo-1234",
"affiliation": "high_fi",
"description": "Preferred purchase",
"purchase_loc": "Palo Alto",
"store_pickup": "unavailable"
};
var content_items = [
{
"$content_schema": "COMMERCE_PRODUCT",
"$og_title": "Nike Shoe",
"$og_description": "Start loving your steps",
"$og_image_url": "http://example.com/img1.jpg",
"$canonical_identifier": "nike/1234",
"$publicly_indexable": false,
"$price": 101.2,
"$locally_indexable": true,
"$quantity": 1,
"$sku": "1101123445",
"$product_name": "Runner",
"$product_brand": "Nike",
"$product_category": "Sporting Goods",
"$product_variant": "XL",
"$rating_average": 4.2,
"$rating_count": 5,
"$rating_max": 2.2,
"$creation_timestamp": 1499892855,
"$exp_date": 1499892854,
"$keywords": [ "sneakers", "shoes" ],
"$address_street": "230 South LaSalle Street",
"$address_city": "Chicago",
"$address_region": "IL",
"$address_country": "US",
"$address_postal_code": "60604",
"$latitude": 12.07,
"$longitude": -97.5,
"$image_captions": [ "my_img_caption1", "my_img_caption_2" ],
"$condition": "NEW",
"$custom_fields": {"foo1":"bar1","foo2":"bar2"}
},
{
"$og_title": "Nike Woolen Sox",
"$canonical_identifier": "nike/5324",
"$og_description": "Fine combed woolen sox for those who love your foot",
"$publicly_indexable": false,
"$price": 80.2,
"$locally_indexable": true,
"$quantity": 5,
"$sku": "110112467",
"$product_name": "Woolen Sox",
"$product_brand": "Nike",
"$product_category": "Apparel & Accessories",
"$product_variant": "Xl",
"$rating_average": 3.3,
"$rating_count": 5,
"$rating_max": 2.8,
"$creation_timestamp": 1499892855
}];
var customer_event_alias = "event alias";
branch.logEvent(
"PURCHASE",
event_and_custom_data,
content_items,
customer_event_alias,
function(err) { console.log(err); }
);
Example Usage for Custom Events
var custom_data = {
"Custom_Event_Property_Key1": "Custom_Event_Property_val1",
"Custom_Event_Property_Key2": "Custom_Event_Property_val2"
};
branch.logEvent(
'custom_event_name',
custom_data,
function(err) { console.log(err); }
);
link
Method | Description |
---|---|
| Creates and returns a Branch Deep Link URL. |
Argument | Type | Description | Required |
---|---|---|---|
|
| Link data and metadata. | Yes |
|
| Callback that returns a string containing the Branch Deep | Yes |
Facebook OG Tags
You can customize the Facebook OG tags of each URL if you want to dynamically share content.
Do this using the following optional keys in the data
object.
Key | Value |
---|---|
| The title you'd like to appear for the link in social media. |
| The description you'd like to appear for the link in social media. |
| The URL for the image you'd like to appear for the link in social media. |
| The URL for the video you'd like to appear for the link in social media. |
| The URL you'd like to appear for the link in social media. |
| If you want to bypass our OG tags and use your own, use this key with the URL that contains your site's metadata. |
Example Usage
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_title': 'My App',
'$og_description': 'My app\'s description.',
'$og_image_url': 'http://myappwebsite.com/image.png'
}
}, function(err, link) {
console.log(err, link);
});
Example Response
callback(
"Status message here",
"https://example.app.link/l/3HZMytU-BW"
);
deepview
See our tutorial for a full guide on how to use Deepview functionality with the Branch Web SDK.
Method | Description |
---|---|
| Turns the current page into a Branch Deepview. A Deepview is a mobile web splash page, hosted by Branch, that gives a preview of the in-app content behind a given Branch Link.
|
Argument | Type | Description | Required |
---|---|---|---|
|
| Object that includes all link data. | Yes |
|
| Includes the following properties: | No |
|
| Callback that returns an error if the API call is unsuccessful. | No |
Example Usage
branch.deepview(
{
channel: 'facebook',
data: {
mydata: 'content of my data',
foo: 'bar',
'$deeplink_path': 'item_id=12345'
},
feature: 'dashboard',
stage: 'new user',
tags: [ 'tag1', 'tag2' ],
},
{
make_new_link: true,
open_app: true
},
function(err) {
console.log(err || 'no error');
}
);
deepviewCta
Method | Description |
---|---|
| Perform the Branch Deepview call to action (CTA) on mobile after |
Argument | Type | Description | Required |
---|---|---|---|
|
| Callback that returns an error if CTA is unsuccessful. | No |
Example Usage
$('a.deepview-cta').click(branch.deepviewCta); // jQuery example
document.getElementById('my-elem').onClick = branch.deepviewCta; // General example
<a href='...' onclick='branch.deepviewCta()'> // In HTML
// We recommend assigning `deepviewCta()` in `deepview()` callback:
branch.deepview(data, option, function(err) {
if (err) {
throw err;
}
$('a.deepview-cta').click(branch.deepviewCta);
});
// You can call `deepviewCta()` any time after `deepview()` is finished
branch.deepviewCta();
// When debugging, call `deepviewCta()` with an error callback
branch.deepviewCta(function(err) {
if (err) {
console.log(err);
}
});
addListener
Method | Description |
---|---|
| An event listener for Journeys-related Branch Events. |
Argument | Type | Description | Required |
---|---|---|---|
|
| Specify which events you would like to listen for. If not defined, the observer will receive all events. | No |
|
| Listening function that receives an event as a string and optional data as an object. | Yes |
Example Usage
var listener = function(event, data) { console.log(event, data); }
// Specify an event to listen for
branch.addListener('willShowJourney', listener);
// Listen for all events
branch.addListener(listener);
Available Journeys Events
Event Name | Description |
---|---|
| Journey is about to be shown. |
| Journey's entrance animation has completed and it is being shown to the user. |
| Journey will not be shown and no other events will be emitted. |
| User clicked on Journey's CTA button. |
| User clicked on Journey's close (X) button. |
| User clicked on the dismiss Journey text. |
| Journey close animation has started. |
| Journey's close animation has completed and it is no longer visible to the user. |
| Emitted when developer calls branch.closeJourney() to dismiss Journey. |
removeListener
Method | Description |
---|---|
| Remove the listener from observations, if it is present. |
Argument | Type | Description |
---|---|---|
|
| Reference to the listening function you would like to remove. |
Example Usage
var listener = function(event, data) { console.log(event, data); }
// Specify an event to listen for
branch.addListener('willShowJourney', listener);
// Remover listener
branch.removeListener(listener);
setBranchViewData
Method | Description |
---|---|
| This function lets you set Branch Deep Link data dynamically for a given mobile web Journey. |
Argument | Type | Description | Required |
---|---|---|---|
|
| Object of all link data. Same as the data object passed to the | Yes |
|
| Callback that returns an error if setting link data fails. | No |
Example Usage
branch.setBranchViewData({
tags: ['tag1', 'tag2'],
data: {
mydata: 'something',
foo: 'bar',
'$deeplink_path': 'open/item/1234'
}
},
function(err) {
if (err) {
console.log(err);
}
});
closeJourney
Method | Description |
---|---|
| Branch Journeys include a close button the user can click, but you may want to close the Journey with a timeout, or via some other user interaction with your web app. |
Argument | Type | Description |
---|---|---|
|
| Callback that returns an error if closing Journey fails. |
Example Usage
branch.closeJourney(function(err) {
if (err) {
console.log(err);
}
});
disableTracking
Method | Description |
---|---|
| Disabling tracking prevents any Branch requests from being sent across the network, except in the case of deep linking. |
Argument | Type | Description | Required |
---|---|---|---|
|
| Set to | No |
|
| Callback that returns an error if tracking status update fails. | No |
Example Usage
branch.disableTracking(
true,
function(err) {
if (err) {
console.log(err);
}
}
);
setDMAParamsForEEA
Warning:
false
by DefaultPlease note that the 3 parameters passed to
setDMAParamsForEEA()
are allfalse
by default.Failure to include user consent signals may result in attribution or campaign performance degradation. For additional information, please reach out to your Google AM.
Method | Description |
---|---|
| Sets the value of parameters required by Google Conversion APIs for DMA Compliance in the EEA region. |
Argument | Type | Description | Required |
---|---|---|---|
|
| Set to | Required if EU regulations apply to this user |
|
| Set to | Required if |
|
| Set to | Required if |
|
| Callback that returns an error if call fails. | No |
Example Usage
The setDMAParamsForEEA()
method can be called before or after the init()
method, and will be queued accordingly:
// Example for an EEA resident who has denied both ad personalization and data usage consent
branch.setDMAParamsForEEA(
true,
false,
false,
function(err) {
if (err) {
console.log(err);
}
}
);