如何在Branch.io API调用中添加事件时关联广告活动

DevOps 小满

2026-7-1

Branch REST API 上报自定义事件关联广告活动标识的解决方法

核心参数说明

要在REST API事件中关联广告活动，必须传递广告活动追踪专属参数，仅用developer_identity或browser_fingerprint_id无法完成归因。这些参数是Branch识别广告活动的关键：

campaign：广告活动名称（对应SDK中的同名字段）
ad_set：广告组名称
ad_name：广告创意名称
channel：推广渠道（如Facebook Ads、Google Ads）
feature：可选功能标识，用于区分不同推广场景

具体请求示例

以POST请求到https://api.branch.io/v1/event为例，请求体需包含广告参数与正确的用户标识：

{
  "branch_key": "你的Branch应用密钥",
  "name": "自定义事件名称",
  "developer_identity": "用户唯一标识",
  "campaign": "夏季促销活动",
  "ad_set": "移动端定向组",
  "ad_name": "首屏横幅广告",
  "channel": "Facebook Ads",
  "event_data": {
    "订单金额": 99.9,
    "商品类型": "电子产品"
  }
}

额外注意事项

若用户通过Branch推广链接跳转而来，传递该链接对应的click_id参数是最精准的关联方式——click_id直接绑定了具体的广告点击会话，可从用户访问时的Branch链接参数中提取。
确保branch_key使用对应环境的密钥（测试/生产），避免归因数据流入错误环境。
若使用browser_fingerprint_id，需保证该ID是通过Branch SDK的getBrowserFingerprintId()方法获取的有效值，而非自定义生成。