Search specific term/phrase surrounded by double quotes. e.g. “deep linking”
Exclude records that contain a specific term prefixed with a minus. e.g. Android -Firebase

Web Advanced Features

Initialize Branch features

branch.init('key_live_OUR_KEY_GOES_HERE', function(err, data) {
console.log(err, data);
});
var options = { no_journeys: true };
branch.init('key_live_YOUR_KEY_GOES_HERE', options, function(err, data) {
  console.log(err, data);
});
  • Returns the following inside the data object
KeyValueTypeRequired
data_parsedIf the user was referred from a link, and the link has associated data, the data is passed in here.object
has_appDoes the user have the app installed already, using Branch's persona data.object
identityUnique string that identifies the user, if set from setIdentitystringN
referring_linkThe referring link clicked, if available.string
referring_identityIf the user was referred from a link, and the link was created by a user with an identity, that identity is here.string

Web SDK Fields

Fields utilized by the Branch Web SDK to provide you with relevant information about end users and linking.

FieldDescriptionExample
identity_idA Branch generated Identity unique to the customer. Used for attribution.identity_id=759504944901509572
sdkThe Branch Web SDK version that was loaded on the webpage.sdk=web2.52.5
session_idA unique ID generated by Branch for the session. Used for attribution.session_id=759504944919560999
browser_fingerprint_idA unique ID generated by Branch for the end user's browser. Used for attribution.browser_fingerprint_id=596017357522557131
alternative_browser_fingerprint_idA unique ID generated by Branch for the end user's browser. This is created as a fallback to browser_fingerprint_idalternate_browser_fingerprint_id=596017357522557245
link_identifierA unique ID generated by Branch for a Branch link click. This is set when a user is referred to the site from a Branch link.
optionsThe Branch SDK initialization options. Includes custom key-value pairs passed in by the customer for tracking purposes
initial_referrerReferral URL that led to the current page where the Branch Web SDK logged web session start. Specified by the client.
tracking_disabledPrevents tracking by the Branch system.
current_urlThe URL where the Branch Web SDK is initialized.
ip_addressEnd user's device IP address.
screen_heightEnd user's device screen height.1080
screen_widthEnd user's device screen width.1920
window_device_pixel_ratioEnd user's device pixel ratio.1
_tShorthand for browser_fingerprint_id._t=596017357522557131
branch_keyThe Branch key used to initialize the Branch Web SDK. These keys are available in the Branch Dashboard.
identityCustom identity for the end user set by the customer. This is not explicitly picked up by the Branch SDK.
instrumentationBranch Web SDK performance metrics.
eventName of the Branch event that initialized the Web SDK. Values can be web_session_start or pageview.event=pageview
metadataCustom metadata sent by the customer at the time of Branch initialization.metadata={"url":"file:///Users/echo/github/web-branch-deep-linking-attribution/example.html","user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130 Safari/537.36","language":"en-US","screen_width":3008,"screen_height":1692,"window_device_pixel_ratio":2,"og_data":{"$og_title":"Branch Metrics Web SDK Example App","$og_description":"A basic example to demonstrate some of the ways that the Web SDK can be used","$og_image_url":"http://branch.io/img/logo_icon_black.png"},"title":"Branch Metrics Web SDK Example App"}
no_journeysBranch Web SDK option to prevent Branch Journeys from showing on the page where the SDK was initialized.
user_languageEnd user browser's language code.en-US
has_app_websdkA probabilistic boolean flag indicating whether the end user has the app installed or not.has_app_websdk=false
sourceWhich Branch SDK initialized the web session.source=web-sdk
featureAnalytics tag set at the time of Branch Web SDK initialization, if applicable.feature=journeys
is_iframeBoolean indicating whether the Branch Web SDK is in an iframe.is_iframe=false
dataDeep link data, if the end user was redirected from a Branch link.data={"$canonical_url":"file:///Users/echo/github/web-branch-deep-linking-attribution/example.html","$og_title":"Branch Metrics Web SDK Example App","$og_description":"A basic example to demonstrate some of the ways that the Web SDK can be used","$og_image_url":"http://branch.io/img/logo_icon_black.png","$og_video":null,"$og_type":null}
user_agentEnd user's browser user agent stringMozilla/5.0 (Windows NT 10.0; Win64; x64; rv:73.0) Gecko/20100101 Firefox/73.0
titleThe title of the web page where the Branch Web SDK was initialized. This title is hosted as part of the meta tags. Only gets returned if available.
descriptionThe description of the web page where the Branch Web SDK was initialized. This title is hosted as part of the meta tags. Only gets returned if available.

Journeys Assist

Journeys Assist allows you to combine your powerful banners and interstitials from Journeys with your mobile measurement capabilities of Universal Ads, Universal Email, and other Branch-powered channels to provide complete attribution of the user flow.

For Multi-Session assists, opt into Journeys assist BEFORE the Branch Web SDK initializes:

var options = { 
  enableExtendedJourneysAssist: true, // enable or disable referring Branch link expiry for Journeys Assist
  extendedJourneysAssistExpiryTime : 5000 // TTL value in milliseconds for the referring Branch link. Defaults to 7 days
};
branch.init('key_live_YOUR_KEY_GOES_HERE', options, function(err, data) {
  console.log(err, data);
});

For more details, please reference our Journeys Assist Guide for more information

Create Deep Link

var linkData = {
  campaign: 'content 123',
  channel: 'facebook',
  feature: 'dashboard',
  stage: 'new user',
  tags: [ 'tag1', 'tag2', 'tag3' ],
  alias: '',
  data: {
    'custom_bool': true,
    'custom_int': Date.now(),
    'custom_string': 'hello',
    '$og_title': 'Title',
    '$og_description': 'Description',
    '$og_image_url':'http://lorempixel.com/400/400'
  }
};

branch.link(linkData, function(err, link) {
  console.log(link);
});

Share Deep Link

  • Will generate a Branch deep link and tag it with the channel the user selects
  • Uses Deep Link Properties
<!-- shareable elements -->
<button id="button">deep link</button>
<a id="anchor" href="#">deep link</a>
var linkData = {
  campaign: 'content 123',
  channel: 'facebook',
  feature: 'dashboard',
  stage: 'new user',
  tags: [ 'tag1', 'tag2', 'tag3' ],
  alias: '',
  data: {
    'custom_bool': true,
    'custom_int': Date.now(),
    'custom_string': 'hello',
    '$og_title': 'Title',
    '$og_description': 'Description',
    '$og_image_url':'http://lorempixel.com/400/400'
  }
};

branch.link(linkData, function(err, link) {
  // bind elements
  document.getElementById('button').onclick = function() {
    window.open(link || err);
  };
  document.getElementById('anchor').href = link || err;
});

Read Deep Link

  • Retrieve Branch data from a deep link
  • Best practice to receive data from the listener (to prevent a race condition)
  • Validate with Testing read deep link
  • Listener
branch.init('key_live_YOUR_KEY_GOES_HERE', function(err, data) {
  console.log(err, data);
});
  • Latest data
branch.data(function(err, data) {
  console.log(err, data);
});
  • First data
branch.first(function(err, data) {
  console.log(err, data);
});

Create Journeys Banner

  • Converts mobile users to app users
  • Create a Journey on the Branch Dashboard
  • Validate by testing your website on a mobile device
  • Append additional deep link data to the Journey button
// optional additional deep link data
var linkData = {
  campaign: 'content 123',
  channel: 'facebook',
  feature: 'dashboard',
  stage: 'new user',
  tags: [ 'tag1', 'tag2', 'tag3' ],
  alias: '',
  data: {
    'custom_bool': true,
    'custom_int': Date.now(),
    'custom_string': 'hello',
    '$og_title': 'Title',
    '$og_description': 'Description',
    '$og_image_url':'http://lorempixel.com/400/400'
  }
};

branch.setBranchViewData(linkData);
// close
branch.closeJourney(function(err, data) {
  console.log(err, data);
});

// reopen
branch.track("pageview");

Create a QR Code

📘

QR Code Access Required

Access to Branch's QR Code API and SDK requires premium product access. Please reach out to your account manager or https://branch.io/pricing/ to activate.

  • Generates a custom QR Code with a unique Branch link which you can deep link and track analytics with.
  • Uses QR Code Settings (1st parameter)
  • Uses Deep Link Properties (2nd parameter)
  • Callback is a qrCode object which contains a rawBuffer or a base64() function which base 64 encodes the raw buffer so that you can use to display the image directly
var qrCodeSettings = {
    "code_color":"#000000",
    "background_color": "#FFFFFF",
    "margin": 5,
    "width": 1000,
    "image_format": "png"
};
var qrCodeLinkData = {
    tags: [ 'tag1', 'tag2' ],
    channel: 'sample app',
    feature: 'create link',
    stage: 'created link',
    data: {
        mydata: 'bar',
        '$desktop_url': 'https://cdn.branch.io/example.html',
        '$og_title': 'Branch Metrics',
        '$og_description': 'Branch Metrics',
        '$og_image_url': 'http://branch.io/img/logo_icon_white.png'
    }
};
branch.qrCode(qrCodeLinkData, qrCodeSettings, function(err, qrCode) {
    // qrCode.rawBuffer is the raw buffer
    // qrCode.base64() is the encoded 
    //
    // Example img tag:
    // <img src="data:image/png;charset=utf-8;base64,' + qrCode.base64() + '" width="500" height="500">
});

For more information on the QR Code API, please reference this guide.

Host Deep Link Data

  • Make it easier for marketers to create deep links
  • Used for Journeys, Universal Emails, Quick links, and the Chrome Extension
  • Branch will scrape the web URL for deep link data on link creation. Note: Branch only scrapes web tags when a new link is created, the Branch scraper will handle 30 redirects until it gets a 200 response, and the maximum number of redirected pages Branch that will scrape data from is 8.
  • If you find Branch cannot scrape your web pages you may need to allowlist our Branch IP addresses and add them to your allow list:
    52.9.159.121/32
    52.9.176.205/32
    52.9.188.221/32
    52.9.188.236/32
  • If you host deep link data in your website source code, Branch can automatically convert a simple web URL into a corresponding Branch link that deep links to relevant content in your mobile app.
  • Branch will also parse your Content Analytics data and provide you with more valuable information about which content is driving clicks, installs, opens, and in-app engagement.
    • The first step to successfully putting deep link data on your website is to understand how your deep links correspond to your web URLs. Ask yourself the following questions, and group your content accordingly.
    • Do you have any content on web that doesn’t exist in the app? Examples include: time-sensitive promotions, splash pages, micro-sites.
    • For content that has corresponding app content, what type of pages do you have? Examples include: search result pages, category homepages, product pages.
    • If you’ve already set up deep linking (if you haven’t set up deep linking skip this step): what does your deep linking schema look like? Do you use different keys for different content? Do you have required key/value pairs that aren’t content specific? Examples include: productPage or categoryPage keys, or product_view=true.
  • Validate by creating a Quick Link and fill in web URL to your web page
Example URLURL dataMetatags to add to your site
https://shop.com/shoes/brown-loafersproductId=1234, productView=true<meta name="branch:deeplink:productId" content="1234" />, <meta name="branch:deeplink:productView" content="true" />
https://shop.com/shoescategoryId=5678<meta name="branch:deeplink:categoryId" content="5678" />
https://shop.com/a-great-movieNo corresponding app content (open web)<meta name="branch:deeplink:$web_only" content="true" />

🚧

Hosted Deep Link Data must be on the site page

When Branch scrapes for this hosted data, no javascript will be run on the page. Therefore, you will need to add the hosted tags directly to the page HTML and should not be injected at page load via javascript or a tag manager.

Setting a custom Deeplink Path when Canonical URL doesn't match App path taxonomy

  • Branch automatically pulls meta tags for your convenience. If Canonical Url is set as a meta tag, it will default this as the Branch $deeplink_path. You can override this by setting $deeplink_path to the path your app url taxonomy uses to deeplink.
<meta name="branch:deeplink:$deeplink_path" content="recipes/456789" />

branch.init('BRANCH_KEY', function(err, data) {
  if (document.querySelectorAll("meta[name='branch:deeplink:$deeplink_path']").length > 0) {
    var meta = document.querySelector("meta[name='branch:deeplink:$deeplink_path']").getAttribute("content");
    branch.setBranchViewData({
      data:{
        '$deeplink_path':meta
      }
    });
  }
});

For more information on the branch:deeplink:Keys you can use to customize your meta tags, please reference this table.

Troubleshooting

  • If you have Facebook App Links metatags on your site and working with your app, then you can skip these instructions. Branch will automatically fetch App Links tags and add them to your deep link data.
  • Do not use Google Tag Manager (GTM) to insert your content metatags. GTM requires JavaScript to load on the page, and the Branch link data scraper does not support JavaScript execution.
  • If you need to allowlist the postback server IP addresses for security purposes, they are listed here.

Track Users

🚧

Sending PII

Be sure to not send any PII through this method. For additional details, please view our guide on Best Practices to Avoid Sending PII to Branch

  • Sets the identity of a user (ID, UUID, etc) for events, deep links, and referrals
  • The value passed to this method must be a string
  • You can validate that the identity was set properly using the Branch Dashboard
branch.setIdentity('123456');
branch.setIdentity('123456', function (err, data) {
  console.log(err, data);
});
  • Removes the identity of a user
branch.logout();
branch.logout(function(err, data) {
console.log(err, data);
});

Track Events

For a complete list of all standard events the Branch SDK tracks, please see Tracking Commerce, Content, Lifecycle and Custom Events.

Commerce Event

  • Registers a custom commerce event
  • Validate with the Branch Dashboard
  • If you track commerce events without a currency, we assume they are USD. If you track commerce events with a currency other than USD, we will convert the revenue specified to USD, using a recent exchange rate.
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": 1499892854966,
   "$exp_date": 1499892854966,
   "$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": 1499892854966
}];

var customer_event_alias = "my custom alias";

branch.logEvent(
   "PURCHASE",
   event_and_custom_data,
   content_items,
   customer_event_alias,
   function(err) { console.log(err); }
);

Content Event

Content events are events that occur when a user engages with your in-app content. For example, if you have in-app articles, you would want to track events related to when users search, view content, rate the content, and share. This can apply to a wide variety of in-app content, such as blog posts, music, video, pictures, and e-commerce catalogue items.

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": 1499892854966,
   "$exp_date": 1499892854966,
   "$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": 1499892854966
}];

var customer_event_alias = "my custom alias";

branch.logEvent(
   "VIEW_ITEMS",
   event_and_custom_data,
   content_items,
   customer_event_alias,
   function(err) { console.log(err); }
);

Custom Event

  • Registers a custom event
  • Events named open, close, install, and referred session are Branch restricted
  • Best to Track users before Track events to associate a custom event to a user
  • Validate with the Branch Dashboard

❗️

Custom Event Name

The name custom event is reserved by Branch. Please ensure you give your custom event an actual name.

We strongly recommend using custom event names that contain no more than 40 characters, contain only letters, numbers, hyphens, spaces and underscores, and do not start with a hyphen.

var custom_data = {
   "Custom_Event_Property_Key1": "Custom_Event_Property_val1",
   "Custom_Event_Property_Key2": "Custom_Event_Property_val2"
};

branch.logEvent(
    event,
    custom_data,
    callback (err)
);

Lifecycle Event

Lifecycle events can be described as events a user takes in your app to continue progressing. These events can apply to game apps, as well as non game apps, for when a user completes a user profile, registration or tutorial.

var event_and_custom_data = {
   "transaction_id": "tras_Id_1234",
   "description": "Preferred purchase",
   "registration_id": "12345"
};

var customer_event_alias = "my custom alias";

branch.logEvent(
   "COMPLETE_REGISTRATION",
   event_and_custom_data,
   content_items,
   customer_event_alias,
   function(err) { console.log(err); }
);

Handle Listeners

  • Subscribe and unsubscribe to Branch events
// all Branch events
branch.addListener(listener);
branch.addListener('willShowJourney', listener);
branch.removeListener(listener);
KeyUsage
willShowJourneyJourney is about to be shown.
didShowJourneyJourney's entrance animation has completed and it is being shown to the user.
willNotShowJourneyJourney will not be shown and no other events will be emitted.
didClickJourneyCTAUser clicked on Journey's CTA button.
didClickJourneyCloseUser clicked on Journey's close button.
willCloseJourneyJourney close animation has started.
didCloseJourneyJourney's close animation has completed and it is no longer visible to the user.
didCallJourneyCloseEmitted when developer calls branch.closeJourney() to dismiss Journey.

Enable / Disable User Tracking

  • In order to help our customers comply with GDPR and other laws that restrict data collection from certain users, we’ve updated our Web SDK with a Do Not Track mode. This way, if a user indicates that they want to remain private on your website, or if you otherwise determine that a particular user should not be tracked, you can continue to make use of the Branch Web SDK (e.g. for creating Branch links) while not tracking that user. This state is persistent, meaning that it’s saved for the user across browser sessions for the web site. This setting can also be enabled across all users for a particular link, or across your Branch links.
  • To enable Do Not Track Mode during initialization, include the tracking_disabled flag, with a value of true, into the options during initialization:
branch.init( 'BRANCH_KEY',
        {
            ‘tracking_disabled’ : true
        }
);
  • To enable Do Not Track Mode following initialization, call disableTracking(true). If you call disableTracking() with no argument, it will default to disableTracking(true). Use disableTracking(false) to resume tracking.

Recommended Next Steps