✕
筛选项
主页指南API 参考
提交工单Branch 操作后台 (Dashboard)Branch 大学Log In
提交工单Branch 操作后台 (Dashboard)Branch 大学

Connected Full Reference

BETA

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.
TizenWebOS
2.36.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>

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 your package.json and rerun npm install

API 参考

init(branch_key, options, callback)

参数

参数类型描述必要项
branch_keystringYour Branch live key, or (deprecated) your app id.Y
optionsObject{ } See options table below.N
callbackfunctionCallback 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 as referring_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, insessionStorage。

📘

Useful Tip

The init function returns a data object where you can read
the link the user was referred by.

选项对象中可用的属性：

Key值类型必要项
advertising_idsThe 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_idThe 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.stringN
retriesdefault: 2numberN
retry_delayexpressed in milliseconds
default: 200ms		numberN
timeoutexpressed in milliseconds
default:5000ms		numberN
tracking_disableddefault: falsebooleanN
enableLoggingdefault: false`booleanN

用途

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)

参数

参数类型描述必要项
callbackfunctionCallback 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)

参数

参数类型描述必要项
callbackfunctionCallback 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

参数

参数类型描述必要项
身份stringA string uniquely identifying the user - often a user ID.Y
callbackfunctionCallback 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)

参数

参数类型描述必要项
callbackfunction注销当前会话，替换会话 ID 和身份 ID。N

用途

branch.logout(
    callback (err)
);

Callback 格式

callback(
     "Error message"
);

getBrowserFingerprintId(callback)

参数

参数类型描述
callbackfunctioncallback 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_windownumberThe number of days to look up attribution data for
callbackfunctionCallback to read last attributed touch dataN

返回当前用户的最后归因触点数据。最后归因触点数据具有与该用户的最近浏览展示或点击链接相关的信息。

用途

branch.lastAttributedTouchData(
    attribution_window,
    callback (err, data)
);

logEvent(event, event_data_and_custom_data, content_items, customer_event_alias, callback)

参数

参数描述必要项
事件StringY
event_data_and_custom_dataObjectN
content_itemsArrayN
customer_event_aliasStringN
callbackfunctionN

通过 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); }
);

链接（数据，回调）

参数

参数类型描述必要项
数据ObjectLink data and metadata.Y
callbackfunctionReturns 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)

参数

参数类型描述必要项
disableTrackingBooleantrue 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 to init(), 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