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:
- Create a Branch Dashboard.
- Integrate the Branch Web SDK into your web app.
- 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:
Field | Description | Example |
---|---|---|
identity_id | A Branch generated identity ID, unique to the customer. Used for attribution. | identity_id=759504944901509572 |
sdk | The Branch Web SDK version that was loaded on the webpage. | sdk=web2.52.5 |
session_id | A unique ID generated by Branch for the session. Used for attribution. | session_id=759504944919560999 |
browser_fingerprint_id | A unique ID generated by Branch for the end user's browser. Used for attribution. | browser_fingerprint_id=596017357522557131 |
alternative_browser_fingerprint_id | A 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_identifier | A 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" |
options | The Branch SDK initialization options. | options={no_journeys:true}; |
initial_referrer | Referral 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_disabled | Disables tracking of users by Branch. | tracking_disabled=true |
current_url | The URL where the Branch Web SDK is initialized. | current_url="https://www.example.com" |
ip_address | End user's device IP address. | ip_address=192.158.1.38 |
screen_height | End user's device screen height. | screen_height=1080 |
screen_width | End user's device screen width. | screen_width=1920 |
window_device_pixel_ratio | End user's device pixel ratio. | window_device_pixel_ratio=1 |
_t | Shorthand for browser_fingerprint_id . | _t=596017357522557131 |
branch_key | The Branch Key used to initialize the Branch Web SDK. Available in the Branch Dashboard. | branch_key=key_live_00000000000 |
identity | Custom identity for the end user set by you. | identity="unique-user-identity-452q389031" |
instrumentation | Branch Web SDK performance metrics. | |
event | Name of the Branch Event that initialized the Branch Web SDK. Values can be web_session_start or pageview . | event=pageview |
metadata | Custom 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_journeys | Whether Branch Journeys should show on the page where the Branch Web SDK was initialized. Default is false . | no_journeys=true |
user_language | End user browser's language code. | user_language=en-US |
has_app_websdk | Probabilistic boolean flag indicating whether the end user has the app installed or not. | has_app_websdk=false |
source | Which Branch SDK initialized the web session. | source=web-sdk |
feature | Analytics tag set at the time of Branch Web SDK initialization, if applicable. | feature=journeys |
is_iframe | Boolean indicating whether the Branch Web SDK is in an iframe. | is_iframe=false |
data | Branch 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_agent | End user's browser user agent string. | Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:73.0) Gecko/20100101 Firefox/73.0 |
title | The 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" |
description | The 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:
-
Create a Journey on the Branch Dashboard.
-
Validate that the Journey was created successfully by testing your website on a mobile device.
-
Append additional Deep Link data to the Journey button:
📄Append Deep Link Data to JourneyOpen Recipe
Journeys Handle Listeners
You can use listeners to subscribe and unsubscribe from event streams related to Journeys.
Events
Event Key | Usage |
---|---|
willShowJourney | Journey is about to be shown. |
didShowJourney | Journey entrance animation is complete and is being shown to user. |
willNotShowJourney | Journey will not be shown, and no other events will be emitted. |
didClickJourneyCTA | User clicked on Journey's CTA button. |
didClickJourneyClose | User clicked on Journey's close button. |
willCloseJourney | Journey close animation has started. |
didCloseJourney | Journey close animation is complete and Journey is no longer visible to user. |
didCallJourneyClose | Emitted 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:
Essentials | Pro |
---|---|
Basic creative types | Advanced creative types |
URL targeting | All targeting |
Desktop and mobile | A/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
orcategoryPage
keys, orproduct_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 URL | Example URL Data | Corresponding HTML Meta Tags |
---|---|---|
https://shop.com/shoes/brown-loafers | productId=1234 , productView=true | <meta name="branch:deeplink:productId" content="1234" /> <meta name="branch:deeplink:productView" content="true" /> |
https://shop.com/shoes | categoryId=5678 | <meta name="branch:deeplink:categoryId" content="5678" /> |
https://shop.com/a-great-movie | No 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:
- Navigate to the Link Manager in the Branch Dashboard.
- Click on the Create button to start creating a new Branch Quick Link.
- 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:
Parameter | Type | Description | Required |
---|---|---|---|
eeaRegion | Boolean | Set 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 |
adPersonalizationConsent | Boolean | Set 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) |
adUserDataUsageConsent | Boolean | Set 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 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.
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.
Updated 7 days ago