Web Advanced Features
Initialize Branch features
- Loads Branch into your app
- Uses Branch init options
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
키 | 값 | 유형 | 필수 |
---|---|---|---|
data_parsed | If the user was referred from a link, and the link has associated data, the data is passed in here. | object | |
has_app | Does the user have the app installed already, using Branch's persona data. | object | |
identity | Unique string that identifies the user, if set from setIdentity | string | N |
referring_link | The referring link clicked, if available. | string | |
referring_identity | If 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.
Field | 설명 | 예시 |
---|---|---|
identity_id | A Branch generated Identity 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. | |
options | The Branch SDK initialization options. Includes custom key-value pairs passed in by the customer for tracking purposes | |
initial_referrer | Referral URL that led to the current page where the Branch Web SDK logged web session start. Specified by the client. | |
tracking_disabled | Prevents tracking by the Branch system. | |
current_url | The URL where the Branch Web SDK is initialized. | |
ip_address | End user's device IP address. | |
screen_height | End user's device screen height. | 1080 |
screen_width | End user's device screen width. | 1920 |
window_device_pixel_ratio | End user's device pixel ratio. | 1 |
_t | Shorthand for browser_fingerprint_id. | _t=596017357522557131 |
branch_key | The Branch key used to initialize the Branch Web SDK. These keys are available in the Twitter Branch dashboard. | |
identity | Custom identity for the end user set by the customer. This is not explicitly picked up by the Branch SDK. | |
instrumentation | Branch Web SDK performance metrics. | |
event | Name of the Branch event that initialized the Web SDK. Values can be web_session_start or pageview. | event=pageview |
metadata | Custom 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_journeys | Branch Web SDK option to prevent Branch Journeys from showing on the page where the SDK was initialized. | |
user_language | End user browser's language code. | en-US |
has_app_websdk | A 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 |
특징 | 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 | Deep 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_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. | |
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. |
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
- Creates a deep link URL with encapsulated data
- Uses Deep Link Properties
- Validate with the Branch Dashboard
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 arawBuffer
or abase64()
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 - 웹사이트 source 코드에서 딥링크 데이터를 호스팅하는 경우 Branch는 간단한 웹 URL을 모바일 앱의 관련 콘텐츠로 딥링크하는 해당 Branch 링크로 자동 전환할 수 있습니다.
- Branch는 또한 여러분의 콘텐츠 분석 데이터를 파싱하고 어떤 콘텐츠가 클릭, 설치, 오픈 및 인앱 인게이지먼트를 유도하는지에 대한 더 중요한 정보를 제공합니다.
- 웹사이트에 딥링크 데이터를 성공적으로 배치하기 위한 첫 번째 단계는 딥링크가 웹 URL과 어떻게 일치하는지 이해하는 것입니다. 다음 질문을 하고 그에 따라 콘텐츠를 그룹화하십시오.
- 앱에없는 콘텐츠가 웹에 있습니까? 예를 들어 시간에 민감한 프로모션, 스플래시 페이지, 마이크로 사이트가 있습니다.
- 해당하는 앱 콘텐츠가있는 콘텐츠의 경우 어떤 유형의 페이지가 있습니까? 예를 들면 다음과 같습니다. 검색 결과 페이지, 카테고리 홈페이지, 제품 페이지.
- 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
orcategoryPage
keys, orproduct_view=true
.
- Validate by creating a Quick Link and fill in
web URL
to your web page
Example URL | URL data | Metatags to add to your site |
---|---|---|
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" /> |
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.
- 콘텐츠 메타 태그를 삽입하기 위해 Google Tag Manager(GTM)를 사용하지 마십시오. GTM을 사용하려면 페이지에 JavaScript가 로드되어야 하며 Branch링크 데이터 스크레이퍼는 JavaScript 실행을 서포트하지 않습니다.
- 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
- Validate with 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 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": 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
, andreferred 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 Event는 사용자의 여정을 심화하기 위해 사용자가 단계별로 발생시키는 일련의 이벤트로 볼 수 있습니다. 이러한 이벤트는 사용자가 회원가입 또는 튜토리얼을 완료할 때 적용될 수 있고 게임 앱과 기타 유형의 앱에도 적용할 수 있습니다.
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);
키 | Usage |
---|---|
willShowJourney | Journey가 곧 공개됩니다. |
didShowJourney | Journey의 entrance animation이 완료되었으며 유저에게 표시되고 있습니다. |
willNotShowJourney | Journey가 표시되지 않으며 다른 이벤트도 발생하지 않습니다. |
didClickJourneyCTA | 유저가 Journey의 CTA 버튼을 클릭했습니다. |
didClickJourneyClose | 유저가 Journey의 닫기 버튼을 클릭했습니다. |
willCloseJourney | Journey close animation이 시작되었습니다. |
didCloseJourney | Journey의 close animiation이 완료되었으며 더 이상 유저에게 표시되지 않습니다. |
didCallJourneyClose | Emitted 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 oftrue
, 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 calldisableTracking()
with no argument, it will default todisableTracking(true)
. UsedisableTracking(false)
to resume tracking.
Updated 27 days ago