使用转化 API 发送线下事件

转化 API 是 Meta 推荐的集成方法，用于将线下事件和实体店铺事件发送到 Meta，以用于广告衡量、归因分析和定位。本页面详细介绍如何通过转化 API 直接集成或合作伙伴集成发送线下事件。

前提条件

数据集

通过转化 API 发送的线下事件必须与某个数据集关联。

您可以向 https://graph.facebook.com/v16.0/{ads-pixel-id}/?fields=is_consolidated_container 发出 GET 调用，以检测广告主的数据集是否经过整合，以及是否符合使用转化 API 发送线下事件的条件。

权限

• 如要以广告主的身份实现直接集成，请按照此处说明操作，了解各项前提条件和权限。

• 如要在合作伙伴平台实现集成，请按照此处说明操作，了解各项前提条件和权限。

配置

1. 设置线下事件参数

广告主可以使用这里提到的设置，并使用当前可通过转化 API 发送的系列参数。如要发送线下事件和店铺事件，可以在有效负载中分享以下字段：

• 对于所有线下事件和店铺事件，广告主在发送时需要将 action_source 为 physical_store。请注意，这个参数对于所有服务器事件类型而言均为必要项。使用转化 API，即表示您同意：据您所知，action_source 参数准确无误。
• 必须按照要求提供转化 API 的所有必要服务器事件字段。
• 客户信息参数（请参阅下文，了解线下事件和店铺事件的相应参数列表）。
• 自定义数据参数（请参阅下文，了解线下事件和店铺事件的相应参数列表）。
• 可选参数：如果广告主使用旧版 API 发送线下事件，仍可以使用 upload_tag 参数上传线下事件。

客户信息参数

以下列表包含通常用于线下事件和店铺事件的客户信息参数：

自定义数据参数

以下部分包含线下事件和店铺事件使用的常用自定义参数。如需使用更多自定义数据字段，请点击此链接，了解我们支持为转化 API 使用的字段的完整清单。

2. 发送事件

如要发送新事件，请通过以下路径向转化 API 发出 POST 请求：https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}

在您向此连线发出 POST 请求后，Meta 会新建线下事件和店铺事件。详情请参阅此开发者文档。

下图简要介绍了各参数如何融入有效负载的整体架构中：

curl -X POST \
  -F 'data=[
       {
  "event_name": "Purchase",
  "event_time": 1674000041,
  "user_data": {
    "em": [
      "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd"
    ],
    "ph": [
      "254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4",
      "6f4fcb9deaeadc8f9746ae76d97ce1239e98b404efe5da3ee0b7149740f89ad6"
    ]
  },
  "custom_data": {
    "currency": "usd",
    "value": 123.45,
    "contents": [{
      "id": "product123",
      "quantity": 1
    }]
  },
  "action_source": "physical_store"
}
]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v15.0/<DATASET_ID>/events

我们建议实时或每天上传，以获得最佳优化结果，从而有效匹配线下数据与您正在投放的任何广告的效果。

event_time 最长可比您向 Meta 发送事件的时间早 7 天。如果 data 中的任何 event_time 早于 7 天前，我们会为整个请求返回错误消息，而且不会处理任何事件。对于线下事件和实体店铺事件（action_source 为 physical_store），您应该在转化后的 62 天内上传发生的事件。

系统会实时处理您上传的数据，因此通常情况下，在您上传数据后即可查看结果。您可以参考帮助中心关于线下事件数据最佳实践的文档。

3. 设置去重

与转化 API 事件和 Meta Pixel 像素代码事件之间的去重设置不同，线下事件只能针对其他线下事件进行去重。我们支持两种去重方法：基于 order_id 的方法或基于 user 方法。去重使用以下字段的组合：dataset_id、event_time、event_name、item_number 以及基于给定事件有效负载中方法的关键字段。

默认情况下，系统会将 order_id 与上述字段的组合搭配使用来实现去重。如果有效负载中没有 order_id，系统将使用基于 user 的去重逻辑。

例如，如果两个订单具有相同的 event_time，并且这些订单的 event_name 具有相同的 order_id 或具有相同的一组客户信息参数但没有 order_id，我们会将这些订单视为重复事件并采用第一个事件。基于 user 的去重方法仅适用于两个有效负载中具有相同客户信息参数的情况。

去重时间期限最长为 7 天。

4. 解决事件问题

您可以使用有效负载设置助手工具来生成有效负载数据：

• 在适用情况下，选择 physical_store 操作来源。使用转化 API，即表示您同意：据您所知，action_source 参数准确无误。
• 填写要发送到 Meta 的事件的相关信息
• 这将生成事件有效负载，该有效负载可用作用于与转化 API 集成的模板

使用事件管理工具中的测试事件工具进行测试。请注意，测试事件工具仅支持网页事件和应用事件。

另请参阅

• 转化 API 概览
• 使用转化 API
• 转化 API 参数
• 最佳实践

Business 帮助中心文章

• 在线下事件集创建过程中创建数据集
• 线下事件数据最佳实践
• 广告主如何使用线下转化量
• 如何查看分配到特定数据集的广告系列的成效
• 如何对线下事件实现去重