Webhooks

概述

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

如果您正在寻找广告平台的回发集成,请访问我们的 Universal Ads文档 。有关与流行的分析工具的预配置集成,请访问我们的数据集成文档

Webhook系统是高度可定制的。您可以注册以仅接收针对特定事件以及事件的特定子节的通知,这些通知按链接数据,用户数据或事件属性进行过滤。

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

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

这些Webhooks包含在Branch的数据馈送产品中,可以根据Branch 定价表进行购买,并且正在为Journeys(网站向App引流解决方案) 通用电子邮件启动和启动计划的客户免费使用。通用广告 。如果没有数据文件,您仍然可以直接通过 CSV导出从分支仪表板以CSV格式直接导出分支数据。

设置

注册webhook

  1. 在“Branch”仪表板上打开“ Webhooks 页面。
  2. 点击+ Add New Webhook

图像

配置Webhook条件

图像

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

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

温馨提示

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

有关事件的详尽列表和每个事件的更详细定义,请参见 Event Ontology Data Schema

警告

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

基本过滤

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

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

下拉列表中提供了最受欢迎的过滤器选项。这将帮助您快速启动并运行,同时还提供了一个示例结构,可根据需要提供更多的高级过滤

要创建过滤器:

  1. 点击Add Filter 按钮
  2. 选择您想要过滤的元数据' 。例如,如果仅安装iOS ,请从下拉列表中选择" Operating System " 。您将看到'右侧的文本字段带有正确的键。稍后进行高级过滤时,您将选择"Custom" 并手动设置此键。
  3. 从下一个下拉列表中选择"equals""does not equal"
  4. 最后,将'想要过滤的键设置为value 。例如,如果要安装iOS,则在下拉菜单中将'设置为"等于"和"IOS" 。在此示例中,机械手过滤器是多余的,因此让'秒钟使用减号按钮将其删除。

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

图像

示例:按归因链接广告系列过滤安装

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

图像

示例:按链接渠道过滤点击

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

图像

请参阅高级过滤页面以了解有关发送事件时进行自定义的更多信息。

Testing

要测试您的Webhook配置是否正确,可以使用 RequestBin 。 RequestBin为您提供了一个接受24小时事件的URL,并允许您确切地看到Branch发送的内容。

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

请求绑定

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

数据格式

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

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

可用回发宏的完整列表

要查找Branch支持的回发宏的完整列表,请参见回发宏&函数

IP 地址差异

对于无法将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
}

进阶筛选

基本过滤我们介绍了过滤器的作用以及如何设置基本过滤器。 Branch支持更高级的过滤,使客户可以基于几乎所有事件元数据设置过滤器。

在尝试设置高级过滤器之前,请确保您已经看过数据格式

要创建过滤器:

  1. 点击Add Filter 按钮
  2. 选择您想要过滤的元数据。要进行高级过滤,请选择 "Custom"
  3. 输入您要筛选的'键。为了找到问题的关键,您' d喜欢上过滤器,参考我们简要介绍了人以诚为本归属' s的数据格式找出在您的钥匙可能嵌套。查找密钥的另一种简单方法是在设置过滤器之前完整查看数据。您可以做一个这样做 CSV出口 API出口或发送一个网络挂接与后机身,并找到在该职位的身体您的关键。
  4. 除非您的密钥是顶层数据的一部分(例如timestampid ),否则它很可能嵌套在一层深处。大多数键的格式为object_name.key 。例如,如果要过滤名为"product_deeplink_id"深度链接接数据中的自定义键,则格式为last_attributed_touch_data.product_deeplink_id

示例:过滤特定优惠券的购买

假设您有兴趣使用特定优惠券在每Purchase 事件中接收一次Webhook。在您的应用或网站中设置购买事件时,您为coupon添加了特定的元数据。在 Event Ontology Schema 您看到couponevent_data内部。要将过滤器配置为仅在coupon 等于SUMMERDEALS10 时才触发Webhook,您将:

  1. 从过滤键下拉列表中选择"自定义"
  2. 设置key为 event_data.coupon
  3. 在下拉列表中选择"equal"
  4. 输入一个值 SUMMERDEALS10

图像

数组过滤尚不可用

当前,webhooks不支持对数组内的值进行过滤。不能由值进行滤波示例阵列是tags+via_featurescontent_items

设置您的回发URL模板

如果您想要设置回发URL的模板,你可能会需要建立我们模板回发网址,沿侧上述过滤器之一。这些工作原理与过滤器非常相似,但是使用Freemarker语法。

模板入门

首先,我们可以添加一个简单的模板。假设'表示我们要添加广告系列作为查询参数。正确的语法是

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

让我们一起熟悉下语法:

  1. 首先,找到您要模板化的键值对。与过滤一样,要找到键,请参考我们对 People-Based Attribution 的数据格式的快速介绍,以了解您的键可能嵌套在何处。查找键的另一种简单方法是在设置过滤器之前先查看完整的数据。您可以尝试做一个 CSV 导出API 导出或发送一个 Webhook 的 POST 请求,并在 POST 体中找到您想要的键。
  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
Bundle Android套件名称 ${(bundle.android.package_name)!}
Bundle iOS Bundle ID ${(bundle.ios.bundle_id)!}
Last Attributed Touch Data 媒介 ${(last_attributed_touch_data.~feature)!}
Last Attributed Touch Data 渠道 ${(last_attributed_touch_data.~channel)!}
Last Attributed Touch Data 广告系列 ${(last_attributed_touch_data.~campaign)!}
Last Attributed Touch Data 广告合作伙伴名称 ${(last_attributed_touch_data.~advertising_partner_name)!}
User Data 操作系统 ${(user_data.os)!}
User Data 平台 ${(user_data.platform)!}
User Data IDFA ${(user_data.idfa)!}
User Data IDFV ${(user_data.idfv)!}
User Data Android广告ID ${(user_data.aaid)!}

可用回发宏的完整列表

要查找Branch支持的回发宏的完整列表,请参见回发宏&函数

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事件

要为您的webhooks请求身份验证标头,请提交票证

支持中心

常见问题

为什么我的webhook无法启动?

检查您的SDK是否处于测试模式。如果您处于测试模式,我们将不会发送网络挂钩。

更新8 天前

Webhooks


建议的编辑仅限于API参考页

您只能建议对Markdown正文内容进行修改,而不能建议对API规范进行修改。