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

Do more with the Branch Web SDK by leveraging advanced features for specific use cases.

Overview

The Branch Web SDK exposes a set of methods specifically made for websites, which you can call using JavaScript.

Prerequisites

Before you get started implementing the features on this page, you first need to:

  1. Create a Branch Dashboard.
  2. Integrate the Branch Web SDK into your web app.
  3. Validate your Branch Web SDK integration.

Web SDK Fields

The Branch Web SDK provides relevant information about end-users and linking using the following fields:

FieldDescriptionExample
identity_idA Branch generated identity ID, 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_id.
alternate_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.link_identifier="348527481794276288"
optionsThe Branch SDK initialization options.options={no_journeys:true};
initial_referrerReferral URL that led to the current page where the Branch Web SDK logged web session start.

Specified by the client.
"initial_referrer=https://www.google.com/"
tracking_disabledDisables tracking of users by Branch.tracking_disabled=true
current_urlThe URL where the Branch Web SDK is initialized.current_url="https://www.example.com"
ip_addressEnd user's device IP address.ip_address=192.158.1.38
screen_heightEnd user's device screen height.screen_height=1080
screen_widthEnd user's device screen width.screen_width=1920
window_device_pixel_ratioEnd user's device pixel ratio.window_device_pixel_ratio=1
_tShorthand for browser_fingerprint_id._t=596017357522557131
branch_keyThe Branch Key used to initialize the Branch Web SDK.

Available in the Branch Dashboard.
branch_key=key_live_00000000000
identityCustom identity for the end user set by you.identity="unique-user-identity-452q389031"
instrumentationBranch Web SDK performance metrics.
eventName of the Branch Event that initialized the Branch Web SDK.

Values can be web_session_start or pageview.
event=pageview
metadataCustom metadata sent by you at the time of Branch initialization.metadata={ "url":"https://github.com/BranchMetrics/web-branch-deep-linking-attribution", "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 of the Branch Web SDK.", "$og_image_url":"<http://branch.io/img/logo_icon_black.png"}, "title":"Branch Metrics Web SDK Example App" }
no_journeysWhether Branch Journeys should show on the page where the Branch Web SDK was initialized.

Default is false.
no_journeys=true
user_languageEnd user browser's language code.user_language=en-US
has_app_websdkProbabilistic 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
dataBranch Deep Link data, if the end user was redirected from a Branch Deep Link.data= {"$canonical_url":"https://github.com/BranchMetrics/web-branch-deep-linking-attribution", "$og_title":"Branch Metrics Web SDK Example App", "$og_description":"A basic example of the Branch Web SDK.", "$og_image_url":"https://branch.io/img/logo_icon_black.png", "$og_video":null, "$og_type":null }
user_agentEnd user's browser user agent string.Mozilla/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.
title="Branch Metrics Web SDK Example App"
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.description="A basic example of the Branch Web SDK."

Browser Fingerprint ID

If you need to access your user's browser fingerprint ID for user deletion, use the getBrowserFingerprintId() method:

branch.getBrowserFingerprintId(function(err, data) { console.log(data); });

Learn more about this method in our Web SDK Full Reference guide.

General Deep Linking

Branch Deep Links are encapsulated with Deep Link properties, which get passed to Branch on a user's click.

Create Deep Links

Use the link() method to create a Branch 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);
});

To test your Branch Deep Link configuration, follow our testing guide.

Share Deep Links

Generate a Branch Deep Link encapsulated with Deep Link properties, and tag it with the channel the user selects.

<!-- 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

You can read a Branch Deep Link to retrieve data from it. This must happen after Branch initialization.

The best practice is to get the data from the listener, since this will prevent a possible race condition.

branch.init('key_live_YOUR_KEY_GOES_HERE', function(err, data) {
  console.log(err, data);
});

// To read latest data, call `data()` method
branch.data(function(err, data) {
  console.log(err, data);
});

// To read first data, call `first()` method
branch.first(function(err, data) {
  console.log(err, data);
});

To test reading a Branch Deep Link, follow our testing guide.

Journeys

Journeys Assist

Branch's Journeys Assist feature combines powerful banners and interstitials from Journeys with the measurement capabilities of Ads, Email, and other Branch-powered channels.

This configuration provides you with complete attribution of the user flow.

Multi Session Assists

For multi session assists, set the value of the enableExtendedJourneysAssist option to true and pass that to the Branch Web SDK during initialization:

var options = { 
  enableExtendedJourneysAssist: true, // Enable referring Branch Link expiry for Journeys Assist
  extendedJourneysAssistExpiryTime : 5000 // TTL value in milliseconds for the referring Branch Link
};
branch.init('key_live_YOUR_KEY_GOES_HERE', options, function(err, data) {
  console.log(err, data);
});

Note that the value of the extendedJourneysAssistExpiryTime option defaults to 7 days.

For more details about Journeys Assist, visit our guide.

Create Journeys Banner

A Branch Journeys Banner helps you convert mobile web users to app users.

To create a Journeys Banner:

  1. Create a Journey on the Branch Dashboard.

  2. Validate that the Journey was created successfully by testing your website on a mobile device.

  3. Append additional Deep Link data to the Journey button:

Journeys Handle Listeners

You can use listeners to subscribe and unsubscribe from event streams related to Journeys.

Events

Event KeyUsage
willShowJourneyJourney is about to be shown.
didShowJourneyJourney entrance animation is complete and is being shown to 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 close animation is complete and Journey is no longer visible to user.
didCallJourneyCloseEmitted when developer calls branch.closeJourney() to dismiss Journey.

Examples

Subscribe to all events:

branch.addListener(listener);

Subscribe to a single event, in this case willShowJourney:

branch.addListener('willShowJourney', listener);

Unsubscribe:

branch.removeListener(listener);

Access

Access to the Journeys feature requires our Engagement package.

There are two tiers in the Engagement package, Essentials and Pro. Each has different Journeys offerings:

EssentialsPro
Basic creative typesAdvanced creative types
URL targetingAll targeting
Desktop and mobileA/B testing

Learn more on our Pricing page.

QR Codes

Branch QR Codes contain a unique Branch Deep Link, which you can use to navigate users to the correct content and for analytics tracking.

To create a Branch QR Code, you'll need to create two JavaScript objects: one for QR Code settings and one for QR Code link params.

Then, call the qrCode() method, passing in the two objects you just created, as well as a callback function that returns the actual QR Code.

Access

Basic Branch QR Codes are included in the free tier of the Branch Growth Platform.

For more advanced QR Code capabilities, see our Engagement Pro package, which includes access to the QR Code API as well as the ability to create custom QR Codes.

Include Deep Link Data in HTML

Hosting data for Branch Deep Links directly in your HTML gives Branch a way to scrape the page for that data and use it when creating a Deep Link. This makes it easier for marketers to create Branch Deep Links.

This approach can be used for Journeys, Emails, Quick Links, and the Chrome Extension.

How It Works

  • During Deep Link creation, provide Branch with a web URL to scrape. Branch will scrape the page for relevant data and include it in the Deep Link properties.
  • If you include link data in your website source code, Branch can automatically convert a simple web URL into a corresponding Branch Deep Link that deep links to relevant content in your mobile app.
  • Branch will parse your Content Analytics data and provide you with more valuable information about which content is driving clicks, installs, opens, and in-app engagement.

Important Considerations

Please note that:

  • Branch only scrapes web tags when a new Deep Link is created.
  • When Branch scrapes for this link data, no JavaScript will run on the page. Therefore, you will need to add the tags hosting the data directly to the HTML. This data should not be injected at page load via JavaScript or a tag manager.
  • The scraper will handle 30 redirects until it gets a 200 response.
  • The maximum number of redirected pages Branch will scrape data from is 8.

Implementation

The first step to successfully including link data in your HTML 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:
    • 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.

Examples

The examples below include the link data Branch should pick up, and the corresponding meta tags that need to be added to the web page for that to happen:

Example URLExample URL DataCorresponding HTML Meta Tags
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" />

Validation

To validate that you are properly including link data in your HTML:

  1. Navigate to the Link Manager in the Branch Dashboard.
  2. Click on the Create button to start creating a new Branch Quick Link.
  3. In the "Original Web URL" box, include the URL for your web page.

Troubleshooting

If you find that Branch cannot scrape your web pages, you may need to put Branch's IP addresses on your allow list:

  • 52.9.159.121/32
  • 52.9.176.205/32
  • 52.9.188.221/32
  • 52.9.188.236/32

Set Custom Deep Link Path

Branch automatically pulls meta tags for your convenience.

If canonical URL is set as a meta tag, it will become $deeplink_path in the Branch system by default.

However, you can override this default setting by manually setting $deeplink_path to the path your mobile app URL taxonomy uses for deep linking. This is done using the content field of the meta tag:

<meta name="branch:deeplink:$deeplink_path" content="recipes/456789" />

branch.init('key_live_YOUR_KEY_GOES_HERE', 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 meta tags on your site that work with your app, then you can skip the instructions in this section. Branch will automatically fetch App Links tags and add them to your Branch Deep Link data.
  • Do not use Google Tag Manager (GTM) to insert your content meta tags. GTM requires JavaScript to load on the page, and the Branch data scraper does not support JavaScript execution.
  • If you need to allowlist the postback server IP addresses for security purposes, they are listed here.

Event Tracking

By default, the Branch Web SDK tracks clicks, opens, installs, reinstalls, impressions, and Journeys dismissals automatically (out-of-the-box).

On web, an open is called a web_session_start. This event is triggered every time a webpage with the web SDK opens in a new tab, or when a user clicks on a Branch link and is redirected to a page with the web SDK.

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 events and the logEvent() method in our guides.

User Data

Google DMA Compliance

In response to the European Union's enactment of the Digital Markets Act (DMA), the Branch iOS SDK includes the setDMAParamsForEEA() method to help you pass consent information from your user to Google.

The setDMAParamsForEEA() method takes 3 parameters:

ParameterTypeDescriptionRequired
eeaRegionBooleanSet to true if user is included in European Union regulations. For example, if the user is located within the EEA, they are within the scope of DMA.

Set to false if user is considered excluded from European Union regulations.
Required if EU regulations apply to this user
adPersonalizationConsentBooleanSet to true if user has granted consent for ads personalization.

Set to false if user has denied consent for ads personalization.
Required if eeaRegion is set to true (i.e., EU regulations apply to this user)
adUserDataUsageConsentBooleanSet to true if user has granted consent for 3P transmission of user-level data for ads.

Set to false is user has denied consent for 3P transmission of user-level data for ads.
Required if eeaRegion is set to true (i.e., EU regulations apply to this user)

Default Behavior

When eeaRegion is set to true, the parameters adPersonalizationConsent and adUserDataUsageConsent must also be set.

When parameters are successfully set using setDMAParamsForEEA(), they will be sent along with every future request to the following Branch endpoints:

  • /v1/install
  • /v1/open
  • /v2/event

🚧

Warning: false by Default

Please note that the 3 parameters passed to setDMAParamsForEEA() are all false 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.

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);

Set User Identity

An "identity" is a unique alias attributed to a specific user in the Branch system.

Some scenarios which could leverage the setIdentity() function:

  • You have your own user IDs that you want to see reflected in the Branch system.
  • You want referral and event data to persist across platforms so you can see how your users access your service from different devices.
  • You want referral and event data to persist across uninstall/reinstall events.

🚧

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.

// Login and set user identity
branch.setIdentity('123456', function (err, data) {
  console.log(err, data);
});

// Logout
branch.logout(function(err, data) {
	console.log(err, data);
});

To confirm that user identities are being set as expected, use the Liveview section of the Branch Dashboard.

Disable Tracking

To disable tracking across your entire website, set the tracking_disabled flag to true and pass that to the init() method during Branch initialization:

branch.init( 'BRANCH_KEY', {‘tracking_disabled’ : true});

If you want to disable tracking after initialization, call the disableTracking() function. Calling this function, either with the parameter true or no parameters, will disable tracking.


Recommended Next Steps