概述

Branch’s webhook system allows you to export install and down-funnel event data as it occurs. You can import this data into your internal systems for analysis. You simply need to specify a URL for the POST or GET requests.

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 系统是可定制的。您可以注册并只接收针对特定事件以子集的通知，这些通知按链接数据、用户数据或事件属性进行筛选。

Our webhook infrastructure supports all Branch events. The data is formatted according to standard event naming and metadata format which will get you through implementation and on to analysis in no time.

📘

数据导出（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：

🚧

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 部分，您可以创建一个筛选项。仅发送通过筛选条件事件。

NOTE: While Branch preserves the original case of all captured data field values and case is retained through export, when webhook/postback filters are evaluated, case-sensitivity is removed. For example, if you created a filter on user_data.os， iOS， ios, and IOS are equivalent.

您会注意到会有一个默认过滤器检查事件是否不是由已知的搜寻器/机器人触发的。为此，我们会检查操作系统是否等同于 “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 。您可以将筛选项配置为仅在 Campaign 为 App Install Campaign 时才触发 Webhook。您将从下拉列表中选择 Campaign ，该 key 将被自动填充，并且等于 last_attributed_touch_data.~campaign 。最后，您可将值设置为 App Install Campaign 。

📘

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

假设您有兴趣接收 Branch Link 中引用的每个 click 事件的 webhook，在其中将 Channel 字段设置为 AppLovin 。您可以将筛选项配置为仅在 Channel 为 AppLovin 时才触发 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:

2. 复制 Endpoint URL ：

3. 将其粘贴到 Branch webhook 的配置屏幕的 URL 字段中：

4. 现在，无论何时触发您的 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 Br 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 是顶层数据的一部分（例如timestamp或id），否则它很可能嵌套在一层深处。大多数 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_features 和 content_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 Branch 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. This exercise tells us that Campaign is nested inside last_attributed_touch_data and is represented by last_attributed_touch_data.~campaign。
3. The additional syntax around last_attributed_touch_data.~campaign is because Branch's templating engine uses Freemarker. In Freemarker, you can print variables by surrounding them with ${}. Finally, we add ()! to the variable because we want to prevent errors in the case that there is no value.
4. This leaves us with ${(last_attributed_touch_data.~campaign)!}。

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

📘

可用回传宏的完整列表

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>"

Allowlist webhook server IP addresses

• If you need to allowlist the webhook server IP addresses for security purposes, they are listed below:
  • 52.9.159.121/32
  • 52.9.176.205/32
  • 52.9.188.221/32
  • 52.9.188.236/32
  • 52.52.143.205
  • 52.53.45.79
  • 52.8.3.171
  • 54.176.26.254

验证 Webhook 事件

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

支持中心

常见问题

• 为什么我的 webhook 无法启动？