初始化 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`

创建深度链接

创建带有封装数据的深度链接 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 a rawBuffer or a base64() 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 or categoryPage keys, or product_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, and referred 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 of true, 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 call disableTracking() with no argument, it will default to disableTracking(true). Use disableTracking(false) to resume tracking.

Web 高级功能

初始化 Branch 功能

创建深度链接

分享深度链接

读取深度链接

创建 Journeys 广告横幅

创建二维码

📘
QR Code Access Required

托管深度链接数据

🚧
Hosted Deep Link Data must be on the site page

Setting a custom Deeplink Path when Canonical URL doesn't match App path taxonomy

问题排查

追踪用户

🚧
Sending PII

追踪事件

Commerce Event

Content 事件

Custom Event

❗️
自定义事件名称

Lifecycle Event

处理侦听器

启用/禁用用户追踪

初始化 Branch 功能

创建深度链接

分享深度链接

读取深度链接

创建 Journeys 广告横幅

创建二维码

📘QR Code Access Required

托管深度链接数据

🚧Hosted Deep Link Data must be on the site page

Setting a custom Deeplink Path when Canonical URL doesn't match App path taxonomy

问题排查

追踪用户

🚧Sending PII

追踪事件

Commerce Event

Content 事件

Custom Event

❗️自定义事件名称

Lifecycle Event

处理侦听器

启用/禁用用户追踪

📘
QR Code Access Required

🚧
Hosted Deep Link Data must be on the site page

🚧
Sending PII

❗️
自定义事件名称