Web 高级功能
初始化 Branch 功能
- 将 Branch 加载到您的应用中
- 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
Key | 值 | 类型 | 必要项 |
---|---|---|---|
data_parsed | 如果用户是从链接引荐过来的,并且该链接具有关联数据,则数据就传送到这里。 | object | |
has_app | 用户是否已使用 Branch 的 Persona (同人用户)数据安装了该应用。 | object | |
身份 | Unique string that identifies the user, if set from setIdentity | string | N |
referring_link | 点击引用链接(如果可用)。 | string | |
referring_identity | 如果用户是从链接引荐过来的,并且该链接由具有身份的用户创建,则该身份就在此处。 | 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. | |
身份 | 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. | |
事件 | 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 |
数据 | 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 |
标题 | 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
创建深度链接
- 创建带有封装数据的深度链接 URL
- 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);
});
分享深度链接
- 生成 Branch 深度链接,并通过用户选择的渠道对其进行标签
- 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;
});
读取深度链接
- 从深度链接中提取 Branch 数据
- 最佳做法是从
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);
});
- 最新数据
branch.data(function(err, data) {
console.log(err, data);
});
- First data
branch.first(function(err, data) {
console.log(err, data);
});
创建 Journeys 广告横幅
- 将移动用户转化为应用用户
- Create a
Journey
on the Branch Dashboard - 通过在移动设备上测试您的网站进行验证
- 将额外的深度链接数据附加到 Journey 按钮
// 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");
创建二维码
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.
- 生成包含唯一 Branch Link 的自定义二维码,您可以使用该 Branch Link 进行深度链接和追踪分析。
- 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.
托管深度链接数据
- 使营销者更容易创建深度链接
- 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 - 如果您在网站源代码中托管深度链接数据,则 Branch 可以自动将简单的 Web URL 转化为对应的 Branch Link,该链接可以深度链接到您的移动应用中的相关内容。
- Branch 还将解析您的 Content Analytics 数据,并为您提供有关哪些内容在推动点击,安装,打开和应用内互动的更有价值的信息。
- 成功将深度链接数据放到您的网站上的第一步是了解深链接如何与您的 Web 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
示例 URL | URL 数据 | 要添加到网站的元标签 |
---|---|---|
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.
问题排查
- 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 追踪标签管理器(GTM)插入您的内容元标记。 GTM 需要在页面上加载 JavaScript,并且 Branch Link 数据抓取工具不支持 JavaScript 执行。
- If you need to allowlist the postback server IP addresses for security purposes, they are listed here.
追踪用户
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);
});
- 删除用户身份
branch.logout();
branch.logout(function(err, data) {
console.log(err, data);
});
追踪事件
For a complete list of all standard events the Branch SDK tracks, please see Tracking Commerce, Content, Lifecycle and Custom Events.
Commerce Event
- 注册自定义 Commerce Event
- Validate with the Branch Dashboard
- 如果您在没有设定货币的情况下追踪 commerce 事件,我们则将其假设为美元。如果您使用非美元的货币追踪 commerce 事件,我们将使用最近的汇率将指定的收入转化为美元。
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 事件
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
- 注册自定义事件
- 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
自定义事件名称
The name
custom event
is reserved by Branch. Please ensure you give your custom event an actual name.我们强烈建议使用不超过40个字符,仅包含字母,数字,连字符,空格和下划线且不要以连字符开头的自定义事件名称。
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); }
);
处理侦听器
- 订阅和取消订阅 Branch 事件
// all Branch events
branch.addListener(listener);
branch.addListener('willShowJourney', listener);
branch.removeListener(listener);
Key | 用途 |
---|---|
willShowJourney | Journey 即将显示。 |
didShowJourney | Journey 的 entrance animation 已经完成,正在向用户显示。 |
willNotShowJourney | Journey 将不会显示,也不会产生任何其他事件。 |
didClickJourneyCTA | 用户点击了 Journey 的 CTA 键。 |
didClickJourneyClose | 用户点击了 Journey 的关闭键。 |
willCloseJourney | Journeys close animation 已开始。 |
didCloseJourney | Journey close animation 已经完成,用户将无法再看到。 |
didCallJourneyClose | 当开发人员调用 branch.closeJourney()以取消 Journey 时发出。 |
启用/禁用用户追踪
- 为了帮助我们的客户遵守 GDPR 和其他限制某些用户收集数据的法律,我们将 Web SDK 更新为 Do Not Track(不追踪)模式。这样,如果用户指示他们希望在网站保持隐私模式,又或者您确定不应该追踪特定用户,则可以在不追踪用户的情况下继续使用 Branch Web SDK(例如,用于创建 Branch Link)。这种状态具有持久性,意味着它已在网站的浏览器会话中为用户进行保存。此设置也可以在所有用户的特定链接或 Branch Link 中启用。
- 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 about 1 month ago