Connected Full Reference
Using the Sample Connected App
We provide a sample app which demonstrates what Branch Metrics Connected SDK can do. The online version can be found at https://cdn.branch.io/connected-example.html. Alternatively, you can open connected-example.html
locally to for the same effect.
To modify this local app, edit src/web/example.template.html
first, and then run make
, which will automatically update connected-example.html
. Refrain from manually editing connected-example.html
。
Minimum Requirements
- The Branch Connected SDK requires native browser Javascript and has only been tested in Tizen and WebOS with sessionStorage capability. No 3rd party libraries are needed to make use of the SDK as is it 100% native Javascript.
Tizen | WebOS |
---|---|
2.3 | 6.0 |
初始化
Add the following script within your <head>
tags:
Be sure to replace BRANCH KEY
with your actual Branch Key found in your account dashboard.
<!doctype html>
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title></title>
<script>
// load Branch
(function (b, r, a, n, c, h, _, s, d, k) {
if (!b[n] || !b[n]._q) {
for (; s < _.length;) c(h, _[s++]);
d = r.createElement(a);
d.async = 1;
d.src = "https://cdn.branch.io/branch-connected.min.js";
k = r.getElementsByTagName(a)[0];
k.parentNode.insertBefore(d, k);
b[n] = h
}
})(window, document, "script", "branch", function (b, r) {
b[r] = function () {
b._q.push([r, arguments])
}
}, {
_q: [],
_v: 1
},
"data first init link logout setIdentity track logEvent disableTracking qrCode"
.split(" "), 0);
// Pass the device's advertising id through 'options' with the corresponding key (https://help.branch.io/developers-hub/docs/connected-basic-integration#advertising-id-index)
const options = {
advertising_ids: {
SAMSUNG_IFA: 'xxxxx',
}
};
// init Branch
branch.init('key_live_YOUR_KEY_GOES_HERE', options);
</script>
</head>
<body></body>
</html>
- Change
key_live_YOUR_KEY_GOES_HERE
to match your Branch Dashboard - If you'd like to use a specific version of the SDK, point to https://cdn.branch.io/branch-connected-x.xx.x.min.js (e.g. https://cdn.branch.io/branch-connected-2.47.1.min.js) rather than https://cdn.branch.io/branch-connected-latest.min.js when initializing.
NPM
npm install branch-connected-sdk
import branch from 'branch-connected-sdk'
// Pass the device's advertising id through 'options' with the corresponding key (https://help.branch.io/developers-hub/docs/connected-basic-integration#advertising-id-index)
const options = {
advertising_ids: {
SAMSUNG_IFA: 'xxxxx',
}
};
// init Branch
branch.init('key_live_YOUR_KEY_GOES_HERE', options);
- Change
key_live_YOUR_KEY_GOES_HERE
to match your Branch Dashboard - If you'd like to use a specific version of the SDK, point to
npm install [email protected]
or update yourpackage.json
and rerunnpm install
API 参考
init(branch_key, options, callback)
参数
参数 | 类型 | 描述 | 必要项 |
---|---|---|---|
branch_key | string | Your Branch live key, or (deprecated) your app id. | Y |
options | Object | { } See options table below. | N |
callback | function | Callback to read the session data. | N |
Adding the Branch script to your page automatically creates a window.branch object with all the external methods described below.
- All calls made to Branch methods are stored in a queue, so even if the SDK is not fully instantiated, calls made to it will be queued in the order they were originally called.
- If the session was opened from a referring link,
data()
will also return the referring link click asreferring_link
, which gives you the ability to continue the click flow. - The init function on the Branch object initiates the Branch session and creates a new user session, if it doesn't already exist, in
sessionStorage
。
Useful Tip
The init function returns a data object where you can read
the link the user was referred by.
选项对象中可用的属性:
Key | 值 | 类型 | 必要项 |
---|---|---|---|
advertising_ids | The current devices advertising id declared by the brand's corresponding key. Please refer to https://help.branch.io/developers-hub/docs/connected-basic-integration#advertising-id-index for more the key index. | {string:string} | Y for Ad Network Attribution N for Web Based Attribution |
branch_match_id | The current user's browser-fingerprint-id. The value of this parameter should be the same as the value of ?branch_match_id (automatically appended by Branch after a link click). _Only necessary if ?_branch_match_id is lost due to multiple redirects in your flow. | string | N |
retries | default: 2 | number | N |
retry_delay | expressed in milliseconds default: 200ms | number | N |
timeout | expressed in milliseconds default:5000ms | number | N |
tracking_disabled | default: false | boolean | N |
enableLogging | default: false | `boolean | N |
用途
branch.init(
branch_key,
options,
callback (err, data),
);
Callback 格式
callback(
"Error message",
{
data_parsed: { }, // If the user was referred from a link, and the link has associated data, the data is passed in here.
referring_identity: '12345', // If the user was referred from a link, and the link was created by a user with an identity, that identity is here.
has_app: true, // Does the user have the app installed already?
identity: 'BranchUser', // Unique string that identifies the user
~referring_link: 'https://bnc.lt/c/jgg75-Gjd3' // The referring link click, if available.
}
);
注意
Branch.init
必须在调用任何其他 Branch function 之前被调用。
data(callback)
参数
参数 | 类型 | 描述 | 必要项 |
---|---|---|---|
callback | function | Callback to read the session data. | N |
返回相同的会话信息和任何引用数据,如下所示:Branch.init
, but does not require the app_id
。
- This is meant to be called after
Branch.init
has been called if you need the session information at a later point. - If the Branch session has already been initialized, the callback will return immediately, otherwise, it will return once Branch has been initialized.
first(callback)
参数
参数 | 类型 | 描述 | 必要项 |
---|---|---|---|
callback | function | Callback to read the session data. | N |
返回相同的会话信息和任何引用数据,如下所示:Branch.init
did when the app was first installed.
- This is meant to be called after
Branch.init
has been called if you need the first session information at a later point. - If the Branch session has already been initialized, the callback will return immediately, otherwise, it will return once Branch has been initialized.
setIdentity(identity, callback)
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
参数
参数 | 类型 | 描述 | 必要项 |
---|---|---|---|
身份 | string | A string uniquely identifying the user - often a user ID. | Y |
callback | function | Callback that returns the user's Branch identity id and unique link. | N |
用途
branch.setIdentity(
identity,
callback (err, data)
);
Callback 格式
callback(
"Error message",
{
randomized_bundle_token: '12345', // Server-generated ID of the user identity, stored in `sessionStorage`.
link: 'url', // New link to use (replaces old stored link), stored in `sessionStorage`.
referring_data_parsed: { }, // Returns the initial referring data for this identity, if exists, as a parsed object.
referring_identity: '12345' // Returns the initial referring identity for this identity, if exists.
}
);
logout(callback)
参数
参数 | 类型 | 描述 | 必要项 |
---|---|---|---|
callback | function | 注销当前会话,替换会话 ID 和身份 ID。 | N |
用途
branch.logout(
callback (err)
);
Callback 格式
callback(
"Error message"
);
getBrowserFingerprintId(callback)
参数
参数 | 类型 | 描述 |
---|---|---|
callback | function | callback to read a user's browser-fingerprint-id |
返回当前用户的 browser-fingerprint-id。如果禁用追踪,则返回 “null”。
用途
branch.getBrowserFingerprintId(function(err, data) { console.log(data); });
Callback 格式
callback(
null,
'79336952217731267', // browser-fingerprint-id, stored in `localStorage`.
);
lastAttributedTouchData(attribution_window, callback)
参数
参数 | 类型 | 描述 | 必要项 |
---|---|---|---|
attribution_window | number | The number of days to look up attribution data for | |
callback | function | Callback to read last attributed touch data | N |
返回当前用户的最后归因触点数据。最后归因触点数据具有与该用户的最近浏览展示或点击链接相关的信息。
用途
branch.lastAttributedTouchData(
attribution_window,
callback (err, data)
);
logEvent(event, event_data_and_custom_data, content_items, customer_event_alias, callback)
参数
参数 | 描述 | 必要项 | |
---|---|---|---|
事件 | String | Y | |
event_data_and_custom_data | Object | N | |
content_items | Array | N | |
customer_event_alias | String | N | |
callback | function | N |
通过 logEvent()注册 commerce 事件,content 事件,user lifecycle 事件和自定义事件
以下指南提供有关触发这些事件类型时可以发送哪些 key 的信息:
Commerce,contnent 和用户生命周期“标准事件”的用法
branch.logEvent(
event,
event_data_and_custom_data,
content_items,
customer_event_alias,
callback (err)
);
“自定义事件”的用法
branch.logEvent(
event,
custom_data,
callback (err)
);
注意事项
- logEvent() sends user_data automatically
- When firing Standard Events, send custom and event data as part of the same object
- Custom Events do not contain content items and event data
Example -- How to log a Commerce 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": 1499892855,
"$exp_date": 1499892854,
"$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": 1499892855
}];
var customer_event_alias = "event alias";
branch.logEvent(
"PURCHASE",
event_and_custom_data,
content_items,
customer_event_alias,
function(err) { console.log(err); }
);
链接(数据,回调)
参数
参数 | 类型 | 描述 | 必要项 |
---|---|---|---|
数据 | Object | Link data and metadata. | Y |
callback | function | Returns a string of the Branch deep linking URL. | Y |
注意
You can customize the Facebook OG tags of each URL if you want to dynamically share content by
using the following optional keys in the data dictionary. Please use thisFacebook tool to debug your OG tags!
Key | 值 |
---|---|
"$og_title" | 您希望在社交媒体上显示链接的标题 |
"$og_description" | 您希望在社交媒体中为链接显示的描述 |
"$og_image_url" | 您希望在社交媒体中显示链接的图片 URL |
"$og_video" | 影片 URL |
"$og_url" | 您希望显示的 URL |
"$og_redirect" | 如果您想绕过我们的 OG 标签并使用自己的 OG 标签,请将此 key 与包含您的网站 metadata的 URL 一起使用。 |
另外,您可以通过在字典插入以下可选 key 来进行自定义重定向:
Key | 值 |
---|---|
"$desktop_url" | 在台式机或笔记本电脑上将用户发送到这里。默认情况下,它是 Branch 托管的 text-me 服务 |
"$android_url" | Play Store 的替代 URL,用于在用户没有该应用的情况下向其发送。仅当您想要移动网站启动时才需要 |
"$ios_url" | App Store 的替代 URL,用于在用户没有该应用的情况下向其发送。仅在您想要移动网站启动时才需要 |
"$ipad_url" | 与上述相同,但适用于 iPad Store |
"$fire_url" | 与上述相同,但适用于 Amazon Fire Store |
"$blackberry_url" | 与上述相同,但适用于 Blackberry Store |
"$windows_phone_url" | 与上述相同,但适用于 Windows Store |
"$after_click_url" | 当用户转到应用后返回浏览器时,将其带到该 URL。仅限 iOS; Android 版即将面世 |
"$afterclick_desktop_url" | 当桌面上的用户转到桌面应用后返回桌面浏览器时,将其带到该 URL。 |
您也可以控制每个链接的直接深度链接:
Key | 值 |
---|---|
"$deeplink_path" | 您希望我们追加到您的 URI 的深度链接路径的值。例如,您可以指定 "$deeplink_path": "radio/station/456",然后我们将使用 URI "yourapp://radio/station/456?link_click_id=branch-identifier" 打开应用。这主要是为了支持旧版深度链接基础架构。 |
"$always_deeplink" | true or false . (default is not to deep link first) This key can be specified to have our linking service force try to open the app, even if we're not sure the user has the app installed. If the app is not installed, we fall back to the respective app store or $platform_url key. By default, we only open the app if we've seen a user initiate a session in your app from a Branch link (has been cookied and deep linked by Branch). |
用途
branch.link(
data,
callback (err, link)
);
例如
branch.link({
tags: [ 'tag1', 'tag2' ],
channel: 'facebook',
feature: 'dashboard',
stage: 'new user',
data: {
mydata: 'something',
foo: 'bar',
'$desktop_url': 'http://myappwebsite.com',
'$ios_url': 'http://myappwebsite.com/ios',
'$ipad_url': 'http://myappwebsite.com/ipad',
'$android_url': 'http://myappwebsite.com/android',
'$og_app_id': '12345',
'$og_title': 'My App',
'$og_description': 'My app\'s description.',
'$og_image_url': 'http://myappwebsite.com/image.png'
}
}, function(err, link) {
console.log(err, link);
});
Callback 格式
callback(
"Error message",
'https://bnc.lt/l/3HZMytU-BW' // Branch deep linking URL
);
disableTracking(disableTracking)
参数
参数 | 类型 | 描述 | 必要项 |
---|---|---|---|
disableTracking | Boolean | true disables tracking and false re-enables tracking. | N |
注意事项
disableTracking()
without a parameter is a shorthand for disableTracking(true).- If a call to
disableTracking(false)
is made, the Connected SDK will re-initialize. Additionally, if tracking_disabled:true
is passed as an option toinit()
, it will be removed during the re-initialization process.
允许用户保持私密
这将防止发送任何 Branch 网络请求(深度链接除外)
。如果有人点击 Branch Link,但又不想被追踪,我们会将深度链接数据返回给
用户,但不会捕获任何追踪信息。
In do-not-track mode, you will still be able to create links and display Journeys however, they will not have identifiable information associated to them. You can change this behavior at any time, by calling the aforementioned function.
The do-not-track mode state is persistent: it is saved for the user across app sessions.
Updated 3 months ago