Webhooks

概述

Branch 基于用户归因的 webhook 系统使您可以在发生安装和转化事件数据时将其导出。您可以将此数据导入内部系统进行分析。您只需要为 POST 或 GET 请求指定一个 URL。

If you are looking for postback integrations for ad networks, please visit our Universal Ads documentation. For pre-configured integrations into popular analytics tools, please visit our Data Integrations documentation.

Webhook 系统是可定制的。您可以注册并只接收针对特定事件以子集的通知,这些通知按链接数据、用户数据或事件属性进行筛选。

我们新的 webhook 基础结构支持所有的 Branch 事件。数据将根据我们更新的事件命名和 metadata格式进行格式化,这将使您立即进行实现并进行分析。

📘

数据导出(Data Feeds)是 Premium 解决方案

The Webhooks are included in Branch’s Data Feeds offering, which can be purchased according to Branch’s pricing schedule. Without Data Feeds, you can still export Branch data in CSV form directly from the Branch dashboard via Sources or CSV Exports.

设置

注册 webhook

  1. Open the Webhooks page on the Branch dashboard.
  2. 点击 + Add New Webhook

图片图片

配置 Webhook 条件

图片图片

填写配置时,您将看到以下选项:

  • Send a webhook to: 输入您想要发送事件的 URL。可以使用 Freemarker 语法编写此 URL,以动态填充参数并执行简单的逻辑表达式。以下是有关 Freemarker 支持中心的更多信息。
  • using a GET/POST: 事件可以通过 POST 或 GET 发送。 POST 事件将使用默认的 POST body 创建。以下是有关 POST body 的更多信息。
  • users trigger event: 发生所选事件时,将触发一个 Webhook:
事件描述
install在用户首次在其设备上启动您的应用时触发。
reinstall当用户在其设备上删除并重新安装您的应用时触发。
open每当打开应用时触发(打开既不是安装也不是重新安装)
web session start当用户使用 Branch Web SDK 查看网页时触发
click在任何平台上点击 Branch Link 时都会触发
-- additional events --您通过 Branch Web 或 App SDK 追踪的事件的完整列表。

🚧

iOS 14.5 发布后的安装事件

Apple requires users to opt into sharing their device data through Apple's AppTrackingTransparency framework. When an install is attributed to paid ads, a 2nd install event will fire post user opt-in

用户是否选择加入将影响您的最终安装数量。我们建议使用一个不同的标识符 (如IDFV) 来对内部系统上的安装事件进行去重。

For additional information on changes post iOS 14.5, visit our FAQ Pages

📘

温馨提示

仅在过去30天内记录了至少一个事件的情况下,事件才会显示在事件下拉列表中。

For an exhaustive list of events and more detailed definitions of each event, please see the Event Ontology Data Schema.

🚧

事件频率

尚不支持限制事件频率。目前,只能在每次事件发生时发送 webhook。

基本筛选

在页面的 Advanced 部分,您可以创建一个筛选项。仅发送通过筛选条件事件

注意:虽然 Branch 保留所有捕获的数据字段值的原始大小写,并且通过导出保留大小写,但是当评估 Webhook/postback 筛选项时,将取消大小写区分。例如,如果您在 user_data.os 上创建了筛选项,则 iOSiosIOS 是等效的。

您会注意到会有一个默认过滤器检查事件是否不是由已知的搜寻器/机器人触发的。为此,我们会检查操作系统是否等同于 “robots”。应用该筛选项后,只有操作系统不等同于 “robots”(即iOS 和 Android)的事件才会触发 Webhook。

The most popular filter options are available in a dropdown. This should help you get up and running quickly, while also providing an example structure for more advanced filtering if you need it.

要创建筛选器,您需要:

  1. 点击 Add Filter
  2. 选择您想要筛选的 metadata。例如,如果仅安装 iOS ,请从下拉列表中选择 "Operating System " 。您将看到右侧的文本字段显示正确的 key。稍后进行高级筛选时,您将选择 "Custom" 并手动设置此 key。
  3. 从下一个下拉列表中选择 "equals""does not equal"
  4. 最后,将想要筛选的 key 设置为 value 。例如,如果要安装 iOS,则在下拉菜单中将设置成 "equals" 和 "IOS" 。在此示例中,机器人筛选项是多余的,因此可以使用减号键将其删除。

这应该是您保存之前的最终视图:

图片图片

📘

示例:按归因链接 campaign 筛选安装

假设您有兴趣接收 Branch Link 中引用的每个 install 事件的 webhook,在其中将 Campaign 字段设置为 App Install Campaign 。您可以将筛选项配置为仅在 CampaignApp Install Campaign 时才触发 Webhook。您将从下拉列表中选择 Campaign ,该 key 将被自动填充,并且等于 last_attributed_touch_data.~campaign 。最后,您可将值设置为 App Install Campaign

图片图片

📘

示例:按链接渠道筛选点击

假设您有兴趣接收 Branch Link 中引用的每个 click 事件的 webhook,在其中将 Channel 字段设置为 AppLovin 。您可以将筛选项配置为仅在 ChannelAppLovin 时才触发 Webhook。您将从下拉列表中选择 Channel ,该 key 将被自动填充,并且等于 last_attributed_touch_data.~channel 。最后,您可将值设置为 AppLovin

图片图片

See the Advanced Filtering page to read more about customizing when events are sent.

测试

To test whether your webhook is configured correctly, you can use RequestBin. RequestBin gives you a URL that accepts events for 24 hours and allows you to see exactly what Branch is sending.

  1. Go to RequestBin and click + Create Request Bin:
  1. 复制 Endpoint URL
  1. 将其粘贴到 Branch webhook 的配置屏幕的 URL 字段中:
  1. 现在,无论何时触发您的 Webhook,您都将在 RequestBin 上看到完整的报告:

🚧

RequestBin

完成测试后,请存档您的 Requestbin Webhook。 Requestbins 仅持续24小时,过期后会返回错误。

数据格式

设置高级筛选项或 Freemarker 宏需要了解事件本体数据格式。在深入了解架构之前,您应该了解有关事件 metadata结构的一些高级概念:

  • 每个事件都有不嵌套的顶级字段,例如 "name" 和 "id"
  • 链接数据通常嵌套在 "Last Attributed Touch Data"
  • 用户数据(包括设备和操作系统数据)嵌套在 "User Data"
  • 产品或内容级别数据嵌套 "Content Items"
  • 交易和通用内容数据嵌套在其中 "Event Data"
  • Journeys (站到端引流) 或 Deepviews 视图数据(例如引流广告条加载,而非点击)为 "Last CTA View Data"
  • 客户端指定的自定义数据(例如,公司在特定事件中需要的内部字段)嵌套在 "Custom Data"

📘

可用回传宏的完整列表

To find a complete list of Branch supported postback macros, please see Postback Macros & Functions.

🚧

知识产权差异

对于无法将 IP 解析到某个位置的事件,只有很少一部分事件无法使用国家和城市等地理数据。

示例 Webhook POST 主体语法

所有 Webhooks 的 POST 主体都采用相同的结构:

POST
User-agent: Branch Metrics API
Content-Type: application/json
{
    "name": "<event name e.g. open>",
    "user_data": {},
    "last_cta_view_data": {},
    "last_attributed_touch_data": {},
    "custom_data": {},
    "event_data": {},
    "content_items": {},
    "timestamp": 'example timestamp (int)'
}

如果这些对象中的任何一个为空,它们将不会出现在 POST 主体中。

此处为 POST 主体,其中包含针对打开的示例数据:

// Attributed open
POST
User-agent: Branch Metrics API
Content-Type: application/json

{
  "name": "open",
  "user_data": {
    "os": "IOS",
    "os_version": "11.1.2",
    "environment": "FULL_APP",
    "platform": "IOS_APP",
    "idfa": "F520B35A-4165-4426-98F6-64F12F47E9BZ",
    "idfv": "C6B869E7-7B0A-4A93-1C3D-960E8859DP5D",
    "limit_ad_tracking": false,
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 11_1_2 like Mac OS X) AppleWebKit/604.3.5 (KHTML, like Gecko) Mobile/15B202",
    "ip": "50.200.105.218",
    "developer_identity": "DB8C86A6-8B7C-4192-BD29-8107A5B788A1",
    "country": "US",
    "language": "EN",
    "brand": "Apple"
  },
  "last_cta_view_data": {
    "~id": 457624031399716729,
    "~campaign": "_test",
    "~feature": "journeys",
    "+domain": "branchster.app.link",
    "+url": "https://branchster.app.link/jeMczRn5XH",
    "$deeplink_path": "open/item/1234",
    "~creation_source": 5,
    "+referrer": "https://store.com/products/green-table",
    "foo": "bar",
    "$canonical_url": "https://store.com/products/green-table",
    "mydata": "set_branch_view_data_value",
    "~tags": [
      "tag1",
      "tag2",
      "bottom_banner_style"
    ]
  },
  "last_attributed_touch_data": {
    "~id": 467391383381228204,
    "~feature": "marketing",
    "~campaign": "december_test",
    "~channel": "Facebook Organic",
    "product_id": "XBA8198j",
    "product_name": "Green Table AB10",
    "+url": "https://branchster.app.link/test_linking",
    "$marketing_title": "Deep Link Testing",
    "$ios_deepview": "branch_default",
    "+via_features": [
      "QUICK_LINKS"
    ]
  },
  "custom_data": {
    "reinstall": "false",
    "ip": "50.200.105.218",
    "referred": "false"
  },
  "timestamp": 1512681005807
}

进阶筛选

In Basic Filtering we covered what filters do, and how to set basic filters. Branch supports more advanced filtering which allows customers to set filters based on almost any event metadata.

Make sure you've taken a look at the data format before you attempt to set advanced filters.

要创建筛选器,您需要:

  1. 点击 Add Filter
  2. 选择您想要筛选的 metadata。要进行高级筛选,请选择 "Custom"
  3. Type in the key that you'd like to filter on. To find the key you'd like to filter on, reference our quick introduction to the People-Based Attribution's data format to figure out where your key is likely nested. Another foolproof way to find your key is looking at your data in full before setting up your filter. You can do this by doing a CSV export, API export or send a single webhook with a POST body, and locate your key in that POST body.
  4. 除非您的 key 是顶层数据的一部分(例如timestampid),否则它很可能嵌套在一层深处。大多数 key 的格式为object_name.key。例如,如果要筛选叫做 "product_deeplink_id" 的深度链接数据中的自定义 key,则格式应为last_attributed_touch_data.product_deeplink_id

📘

示例:筛选特定优惠券的购买

Let’s say you’re interested in receiving a webhook for every Purchase event using a specific coupon. When you set up the Purchase event in your app or on your website, you added a specific piece of metadata for coupon. In the Event Ontology Schema you saw that coupon is inside event_data. To configure your filter to fire a webhook only when coupon is equal to SUMMERDEALS10 you will:

  1. 从筛选 key 下拉列表中选择 "Custom"
  2. 将 key 设为 event_data.coupon
  3. 在下拉列表中选择 "equals"
  4. 输入值 SUMMERDEALS10

图片图片

🚧

数组筛选尚不可用

当前,webhooks 不支持对数组内的值进行筛选。不能由值进行筛选的示例阵列为 tags+via_featurescontent_items

设置您的回传 URL 模板

如果您想要设置回传 URL 的模板,你可能会需要建立我们模板回传的 RUL 以及上述的筛选项。这些工作原理与筛选项非常相似,但使用的是 Freemarker 语法。

模板入门

首先,我们可以添加一个简单的模板。假设我们要添加 Campaign 作为查询参数。正确的语法是

`https://webhook.com?campaign=${(last_attributed_touch_data.~campaign)!}`

让我们一起熟悉下语法:

  1. First, find the key for the value you want to template in. As with filtering, to find the key, reference our quick introduction to the People-Based Attribution's data format to figure out where your key is likely nested. Another foolproof way to find your key is looking at your data in full before setting up your filter. You can do this by doing a CSV export, API export or send a single webhook with a POST body, and locate your key in that POST body.
  2. 例如,此练习告诉我们 Campaign 嵌套在 last_attributed_touch_data 中,并由 last_attributed_touch_data.~campaign 表示。
  3. last_attributed_touch_data.~campaign 中的附加语法是因为 Branch 的模板引擎使用 Freemarker。在 Freemarker 中,您可以通过用 ${} 包围变量来打印变量。最后,将()! 加到变量中是因为我们要在没有值的情况下防止错误。
  4. 这使我们最终得到 ${(last_attributed_touch_data.~campaign)!}

这是一些常用模板的 Freemarker 示例:

父对象通用名Freemarker
BundleAndroid 包名${(bundle.android.package_name)!}
BundleiOS Bundle ID${(bundle.ios.bundle_id)!}
最后归因触点数据功能${(last_attributed_touch_data.~feature)!}
最后归因触点数据渠道${(last_attributed_touch_data.~channel)!}
最后归因触点数据Campaign${(last_attributed_touch_data.~campaign)!}
最后归因触点数据广告合作伙伴名称${(last_attributed_touch_data.~advertising_partner_name)!}
用户数据操作系统${(user_data.os)!}
用户数据平台${(user_data.platform)!}
用户数据IDFA${(user_data.idfa)!}
用户数据IDFV${(user_data.idfv)!}
用户数据Android 广告 ID${(user_data.aaid)!}

📘

可用回传宏的完整列表

To find a complete list of Branch supported postback macros, please see Postback Macros & Functions.

Freemarker 表达式

由于安全限制,Branch 不支持所有的 Freemarker 表达式。

这是被阻止的表达式列表:

"<#import>", "<#visit>", "<#include>", "?eval", "<#recurse>", "<#setting>", "<#macro>", "<#function>", "<#nested>", "<#return>", "<#list>"

将 Webhook 服务器 IP 地址列入白名单

  • 如果出于安全考虑需要将 Webhook 服务器 IP 地址列入白名单,则它们将在下面列出:
    • 52.9.159.121/32
    • 52.9.176.205/32
    • 52.9.188.221/32
    • 52.9.188.236/32

验证 Webhook 事件

To request authentication headers for your webhooks, please Submit a Ticket .

支持中心

常见问题


这个页面对您有帮助吗?