筛选项

Web 高级功能

初始化 Branch 功能

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 setIdentitystringN
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_idA Branch generated Identity unique to the customer. Used for attribution.identity_id=759504944901509572
sdkThe Branch Web SDK version that was loaded on the webpage.sdk=web2.52.5
session_idA unique ID generated by Branch for the session. Used for attribution.session_id=759504944919560999
browser_fingerprint_idA unique ID generated by Branch for the end user's browser. Used for attribution.browser_fingerprint_id=596017357522557131
alternative_browser_fingerprint_idA unique ID generated by Branch for the end user's browser. This is created as a fallback to browser_fingerprint_idalternate_browser_fingerprint_id=596017357522557245
link_identifierA 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.
optionsThe Branch SDK initialization options. Includes custom key-value pairs passed in by the customer for tracking purposes
initial_referrerReferral URL that led to the current page where the Branch Web SDK logged web session start. Specified by the client.
tracking_disabledPrevents tracking by the Branch system.
current_urlThe URL where the Branch Web SDK is initialized.
ip_addressEnd user's device IP address.
screen_heightEnd user's device screen height.1080
screen_widthEnd user's device screen width.1920
window_device_pixel_ratioEnd user's device pixel ratio.1
_tShorthand for browser_fingerprint_id._t=596017357522557131
branch_keyThe 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.
instrumentationBranch Web SDK performance metrics.
事件Name of the Branch event that initialized the Web SDK. Values can be web_session_start or pageview.event=pageview
metadataCustom 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_journeysBranch Web SDK option to prevent Branch Journeys from showing on the page where the SDK was initialized.
user_languageEnd user browser's language code.en-US
has_app_websdkA probabilistic boolean flag indicating whether the end user has the app installed or not.has_app_websdk=false
sourceWhich 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_iframeBoolean 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_agentEnd user's browser user agent stringMozilla/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.
descriptionThe 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

创建深度链接

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
示例 URLURL 数据要添加到网站的元标签
https://shop.com/shoes/brown-loafersproductId=1234, productView=true<meta name="branch:deeplink:productId" content="1234" /><meta name="branch:deeplink:productView" content="true" />
https://shop.com/shoescategoryId=5678<meta name="branch:deeplink:categoryId" content="5678" />
https://shop.com/a-great-movieNo 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 opencloseinstall, 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用途
willShowJourneyJourney 即将显示。
didShowJourneyJourney 的 entrance animation 已经完成,正在向用户显示。
willNotShowJourneyJourney 将不会显示,也不会产生任何其他事件。
didClickJourneyCTA用户点击了 Journey 的 CTA 键。
didClickJourneyClose用户点击了 Journey 的关闭键。
willCloseJourneyJourneys close animation 已开始。
didCloseJourneyJourney 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.

后续步骤推荐