桌面和 Over the Top (OTT) 归因

概述

Branch 支持所有桌面和 over-the-top(OTT)平台的服务器间 (server-to-server)(S2S)的测量。

本文档概述了如何发送会话和转化事件。这些是独立的,因为会话从根本上不同于转化事件。请求到 Branch 以记录会话的响应可以包括深度链接数据。这可用于将用户与内容进行深度链接,包括“延迟深度链接”方案,即用户点击链接,然后安装应用并打开它。

We use Roku as the basis for this guide, but applies to other OTT solutions. We provide an example request (curl), then we discuss each parameter in the request. For specific parameters, we provide tables showing how to change the request based on the platform (e.g. Amazon Fire TV, Apple TV, Samsung Smart TV).

📘

API 访问受到限制

直接调用 v1/open API 的功能仅限于部分企业帐户。请联系您的 Branch 客户经理,以确认您的帐户是否符合条件。

先决条件

  • App is setup in the Branch dashboard with default link redirects, your app.link domains, a URI scheme, Universal Links, and you have access to your API & Secret keys
  • 帐户已允许访问 v1/open API

📘

需要进行操作后台 (Dashboard) 以及应用内设置

Successful use of the v1/open API will require setup steps in the Branch dashboard and in your mobile or OTT/CTV app.

会话统计请求

A session measurement request should be made every time the app is opened. The response should be parsed and a few of the values should be used on subsequent requests (i.e. randomized_device_token, randomized_bundle_token).

会话请求参数

参数

类型

定义

branch_key

String

创建操作后台 (Dashboard) 时提供的 Branch key。

branch_secret

String

创建操作后台 (Dashboard)时提供的 Branch secret。

server_to_server

Boolean

将此项在请求中 hardcode 为 true。

app_version

String

您应用的 sementic 版本 ID。

操作系统

String

See platform specific key-value section.

os_version

String

操作系统 sementic 版本 ID。

retryNumber

Integer

默认值为0。如果重试请求,则将其设置为1(第一次重试)或2(第二次重试)。

品牌

String

设备品牌。

模型

String

设备型号。

screen_height

Integer

屏幕的高度。

screen_width

Integer

屏幕的宽度。

ad_tracking_enabled

Boolean

确保已传递,以便 Branch 可以利用此标记。

advertising_ids

String 映射→ String

Should include the appropriate key for the device, and then the value of that advertising ID. See [platform specific key-value section(#session-platform-specific-key-values).

launch_options

仅限 Roku

启动或输入请求上的查询参数映射,以及作为这些命令的一部分可能传递给 Roku 应用的其他 metadata。

示例:以下命令将发布到您的应用:
curl -d '' 'http://192.168.0.1:8060/launch/dev?contentId=1234&mediaType=movie'

randomized_device_token

String

On initial request (i.e. install), omit this key. Will be returned in the first response (e.g. "randomized_device_token": "123456789123456789"). Then send this up on subsequent requests.

server_to_server_identity

Boolean

Hard code this into the request as true. This generates the randomized_bundle_token for the s2s requests and returns in the response. This needs to be accompanied by identity below.

身份

String

Only works with the server_to_server_identity

进行 s2s 调用时,将其映射并设置为 developer_id。示例 — "test_user_01”

link_identifier

String

URI 打开 App 时,检查 link_click_id
查询项,并使用该值填充(如果缺少,则不包含在请求中)

例如 yourapp://open?link_click_id=823569794275788167

会话平台特定的 Key 值

mac_OS

  • os: mac_OS
  • advertising_ids: idfa
    • 示例: "idfa": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

WINDOWS

  • 操作系统: WINDOWS
  • advertising_ids: windows_advertising_id
    • 示例: "windows_advertising_id": "ea31e5e0"

tv_OS

  • os: tv_OS
  • advertising_ids: idfa
    • 示例: "idfa": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

Roku

  • 操作系统:ROKU
  • advertising_ids: roku_rida
    • 示例: "roku_rida": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

三星

  • 操作系统:三星
  • advertising_ids: samsung_ifa
    • 示例: "samsung_ifa": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

LG

  • 操作系统:LG
  • advertising_ids: lg_ifa
    • 示例: "lg_ifa": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

松下

  • 操作系统:松下
  • advertising_ids: panasonic_ifa
    • 示例: "panasonic_ifa": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

XBOX

  • 操作系统:XBOX
  • advertising_ids: xbox_msai
    • 示例: "xbox_msai": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

请求示例

curl -d '{
  "branch_key": "key_live_YOUR_KEY_HERE",
  "app_version": "1.0.1",
  "os": "ROKU",
  "os_version": "10.0",
  "retryNumber": 0,
  "brand": "Roku",
  "model": "4200X",
  "sdk": "roku",
  "sdk_version": "1.0.0",
  "screen_height": 1334,
  "screen_width": 750,
  "ad_tracking_enabled": true,
  "advertising_ids": {
    "roku_rida": "00000000-0000-0000-0000-000000000123"
  },
  "launch_options": {
    "contentID": "1234",
    "instant_on_run_mode": "foreground",
    "lastExitOrTerminationReason": "EXIT_UNKNOWN",
    "mediaType": "movie",
    "source": "external-control",
    "splashTime": "1500"
  },
  "randomized_device_token": "123456789123456789",
  "randomized_bundle_token": "987654321987654321"
}' "https://api2.branch.io/v1/open"

响应示例

{
  "data": "{\"+clicked_branch_link\":true,\"+is_first_session\":false,\"contentID\":\"1234\",\"mediaType\":\"movie\"}",
  "randomized_device_token": "123456789123456789",
  "randomized_bundle_token": "987654321987654321",
  "session_id": "685187705776489500"
}

NOTE: The deep link data is located inside the object data. It includes +clicked_branch_link: true as well as the link data.

转化事件衡量

转化事件包括会话以外的所有内容。包括注册,内容浏览,购买等。

对于 Standard Events(一般事件),请提出以下要求: /v2/event/standard

如果要追踪不在此列表中的事件,则可以设为追踪自定义事件。这些将不能很好地映射到第三方事件名称,因此,如果没有良好的 Standard Events(一般事件)可用,这应该是一个后备方法。

📘

Branch 标准事件

For a full list of Branch Standard Events, please see this document.

对于 Standard Events(一般事件),请提出以下要求: /v2/event/custom

转化事件请求参数

参数

类型

定义

名称

String

如果使用 /v2/event/standard,则应为 Standard Events(一般事件)名称。否则,如果使用 /v2/event/custom,则可以是自定义事件名称(任何 string)。

customer_event_alias

String

可以是任何 string。

branch_key

String

创建操作后台 (Dashboard) 时提供的 Branch key。

必要项

user_data.developer_identity

String

您的用户 ID。

user_data.app_version

String

您应用的 sementic 版本 ID。

user_data.os

String

See platform specific key-value section.

user_data.os_version

String

操作系统 sementic 版本 ID。

user_data.brand

String

设备品牌。

user_data.model

String

设备型号。

user_data.screen_height

Integer

屏幕的高度。

user_data.screen_width

Integer

屏幕的宽度。

user_data.environment

String

See platform specific key-value section.

user_data.limit_ad_tracking

Boolean

确保已传递,以便 Branch 可以利用此标记。Inverse of /v1/open -> ad_tracking_enabled

user_data.advertising_ids

String 映射→ String

Should include the appropriate key for the device, and then the value of that advertising ID. See platform specific key-value section.

user_data.randomized_device_token

String

On initial request (i.e. install), omit this key. Will be returned in the first response (e.g. "randomized_device_token": "123456789123456789"). Then send this up on subsequent requests.

event_data.transaction_id

String

您事件的交易 ID。

event_data.currency

String (enum)

ISO-4217 Currency Codes Only

event_data.revenue

Double / float

该交易的收入金额。

retryNumber

Integer

默认值为0。如果重试请求,则将其设置为1(第一次重试)或2(第二次重试)。

转化事件平台特定的 Key 值

mac_OS

  • user_data.os: mac_OS
  • user_data.environment: DESKTOP_APP
  • user_data.advertising_ids: idfa
    • 示例: "idfa": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

WINDOWS

  • user_data.os: WINDOWS
  • user_data.environment: DESKTOP_APP
  • user_data.advertising_ids: windows_advertising_id
    • 示例: "windows_advertising_id": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

Roku

  • user_data.os: ROKU
  • user_data.environment: TV_APP
  • user_data.advertising_ids:roku_rida
    • 示例: "roku_rida": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

三星

  • user_data.os: SAMSUNG
  • user_data.environment: TV_APP
  • user_data.advertising_ids: samsung_ifa
    • 示例: "samsung_ifa": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

LG

  • user_data.os: LG
  • user_data.environment: TV_APP
  • user_data.advertising_ids: lg_ifa
    • 示例: "lg_ifa": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

松下

  • user_data.os: PANASONIC
  • user_data.environment: TV_APP
  • user_data.advertising_ids: panasonic_ifa
    • 示例: "panasonic_ifa": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

XBOX

  • user_data.os: XBOX
  • user_data.environment: TV_APP
  • user_data.advertising_ids: xbox_msai
    • 示例: "xbox_msai": "ea31e5e0-1aa5-4181-91d7-0b56524e0274"

样品申请

curl -d '{
  "name": "PURCHASE",
  "customer_event_alias": "purchase 5 tokens",
  "branch_key": "key_live_nezyBshNogxltEUiFjKaDbmkrDlwphCf",
  "user_data": {
    "developer_identity": "user123",
    "app_version": "1.0.1",
    "os": "ROKU",
    "os_version": "10.0",
    "brand": "Roku",
    "model": "4200X",
    "sdk": "roku",
    "sdk_version": "1.0.0",
    "screen_height": 1334,
    "screen_width": 750,
    "environment": "TV_APP",
    "limit_ad_tracking": false,
    "advertising_ids": {
      "roku_rida": "00000000-0000-0000-0000-000000000123"
    },
    "randomized_device_token": "123456789123456789"
  },
  "event_data": {
    "transaction_id": "foobar",
    "currency": "USD",
    "revenue": 100
  },
  "retryNumber": 0
}' "https://api2.branch.io/v2/event/standard"

响应示例

您无需检查响应的 body 部分。只需查找 200 HTTP 状态代码。Non-2xx 状态代码表示错误。


这个页面对您有帮助吗?