线下转化 API

使用线下转化 API 发送线下转化事件以及查看有多少客户在转化之前浏览或点击了 Meta 广告。

准备工作

要使用此 API，您需要有：

1. Meta 商务管理平台

如果没有商务管理平台，请创建一个。

2. Meta 应用编号

用于访问市场营销 API。如要创建 Meta 应用，请执行以下操作：

• 访问商务管理平台 > 业务设置。
• 选择应用。
• 点击添加新应用并按照说明操作。

3. 应用审核和权限

应用审核和权限的相关规则视 API 的实现方法而定：

4. 商务管理平台系统用户和口令

有了系统用户访问权限，您的应用就可以使用 API 向 Meta 发送数据。如要创建系统用户，请按以下步骤操作：

• 访问商务管理平台 > 业务设置。
• 选择系统用户。
• 点击添加新系统用户。
• 将管理员级系统用户选作系统用户身份。

有了访问口令，您的应用就可以访问 Meta 数据。如要创建系统用户访问口令，请按以下步骤操作：

• 访问商务管理平台 > 业务设置。
• 选择系统用户。
• 选择系统用户，然后点击生成新口令。
• 选择您的应用，将 ads_management 选作范围。

5. 广告账户

您需要使用广告账户才能在 Meta 上投放广告系列。如要创建广告账户，请参阅市场营销 API，或 Business 帮助中心：Meta 商务管理平台中的业务设置简介。

6. 向系统用户授予广告账户的访问权限

向您的系统用户授予广告账户的访问权限。

• 转到商务管理平台 > 业务设置。
• 选择系统用户。
• 选择系统用户，然后点击分配资产。
• 选择您的广告账户。

7. 线下事件集

线下事件集是指包含线下转化数据的上传文件。创建广告时，将 tracking_spec 设置为线下事件集编号，以便正确归因事件。之后，您可以在商务管理平台中创建事件集、查看关于所导入事件的数据、删除和修改这些数据。

对于之前实现的 API，您可以在商务管理平台层级对线下事件集执行 CRUD 操作，以便与其他对象和实体共享事件集。

上传事件数据

您需要使用特定访问权限才能创建线下事件集、上传或查看事件集数据。而且，您需要使用此访问权限才能向广告账户分配这些权限。您的身份必须是下列其中一项：

• 商务管理平台管理员
• 创建线下事件集的管理员级系统用户
• 与线下事件集关联的 ad_account 管理员

请参阅参考文档的“线下转化事件集”部分。

1. 创建线下事件集

curl 
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' 
  -F 'name=offline_event_set',
  -F 'description=conversion data used for superbowl campaign',
  https://graph.facebook.com/<API_VERSION>/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

发出 HTTP POST 请求：

POST /<BUSINESS_MANAGER_ID>/offline_conversion_data_sets HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

响应中包含事件集 id：

{
  "id": <OFFLINE_EVENT_SET_ID>
}

参数

2. 分配广告账户权限

向广告账户分配追踪和读取权限：

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

参数

3. 设置广告追踪

您更新 tracking_spec 时，我们会覆盖此设置。请务必先执行 GET 请求，然后将线下事件集的关联 String 附加到现有 tracking_spec 中。请参阅广告管理或使用广告管理工具。例如，提供适当的追踪参数：

curl \
  -F 'tracking_spec=[{action.type:"offline_conversion", dataset:["123"]}]' \
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<AD_ID>

更新广告的追踪参数：

POST /<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}] HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}]

参数

4. 上传线下事件

您应该在转化发生后的 62 天内上传交易。上传转化数据：

curl \
  -F 'access_token=SYSTEM_USER_ACCESS_TOKEN' \
  -F 'upload_tag=store_data' \
  -F 'data=[ \
    { 
      match_keys: {"phone": ["HASH1","HASH2"], "email": ["HASH3","HASH4"]}, 
      currency: "USD", 
      value: 16,
      event_name: "Purchase",
      event_time: 1456870902,
      contents: [
        {id: "A", quantity: 1},
        {id: "B", quantity: 2},
        {id: "C", quantity: 1}
      ]
      custom_data: {             
      },
    }, 
    { 
      match_keys: {"lead_id": "12345"}, 
      event_name: "Lead",
      event_time: 1446336000,
      contents: [
        {id: "A", quantity: 1},
        {id: "B", quantity: 2},
        {id: "C", quantity: 1}
      ]
      custom_data: {
        event_source: "email",
        action_type: "sent_open_click",
        email_type: "email_type_code", 
        email_provider: "gmail_yahoo_hotmail",
      }
    }, 
  ]'
  https://graph.facebook.com/VERSION/OFFLINE_EVENT_SET_ID/events

如要发送转化事件，请发出 HTTP POST 请求：

POST /<OFFLINE_EVENT_SET_ID>/events HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/events

参数

在同一批次的所有事件上传 API 调用中使用相同的 upload_tag，以便将这些调用分为同一组。这有助于调试事件上传，因此在通过多次 API 调用执行任何事件上传操作时，应使用此方法。

data 中的参数包括：

例如，可以上传带有 data 字段的信息：

{
  match_keys: MATCH_KEYS,
  event_time: EVENT_TIME,
  event_name: "Purchase",
  value: 400,
  currency: "USD",
  contents: [
    {
        id: "A",
        quantity: 1,
        brand: "brand_of_A",
        category: "Apparel & Accessories | Clothing",
        price: 100,
    },
    {
        id: "B",
        quantity: 2,
        brand: "brand_of_B",
        category: "Apparel & Accessories | Shoes",
        price: 50,
    },
    {
        id: "C",
        quantity: 1,
        brand: "brand_of_C",
        category: "Apparel & Accessories | Jewelry | Watches",
        price: 200,
    }
  ],
}

在同一批次的所有事件上传 API 调用中使用相同的 upload_tag，以便将这些调用分为同一组。这有助于调试事件上传，因此在通过多次 API 调用执行任何事件上传操作时，应使用此方法。

匹配键

match_keys 是匹配用户的一组标识符，可用于进行归因。请参阅来自 CRM 数据的自定义受众，了解如何规范数据和对数据进行哈希处理。我们仅支持 SHA256，不接受未经过哈希处理的数据。

响应：

出现错误时，您会看到一条异常消息，其中包含无效条目和相关原因。请纠正错误，或跳过存在错误的数据行并重新尝试调用 API。

查看上传统计数据

商务管理平台的管理员或创建线下事件集的系统用户可以检索上传数据。此外，与线下事件集关联的任何 ad_account 管理员都可以读取该数据。

查看关于线下事件集的数据，如有效条目和匹配条目：

GET /<OFFLINE_EVENT_SET_ID>/uploads HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/uploads

在商务管理平台的 Offline Events Manager 中查看线下事件的每日细分数据。如需获取更精准的细分数据，请发出如下调用：

GET /<OFFLINE_EVENT_SET_ID>/stats HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/stats

参数

创建线下自定义转化事件

目前，系统不会回填线下自定义转化事件。我们不会归因您创建自定义转化事件之前上传的事件数据。您无法使用线下自定义转化事件数据优化广告投放。请参阅参考文档 > 自定义转化事件。

如要使用线下事件创建自定义转化事件，请发出 POST 请求：

POST /act_<ACCOUNT_ID>/customconversions HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/act_<ACCOUNT_ID>/customconversions

参数：

若请求成功，响应如下：

{
  "id": <CUSTOM_CONVERSION_ID>
}

通过自定义数据衡量成效

可以使用 custom_data 字段创建规则，以便之后确定是否统计某转化事件。这与线下自定义受众类似。每个广告账户可以有多达 40 个自定义转化事件。

例如，通过 custom_data 在上传数据中添加商品类别：

data=[
  {
    match_keys: {"phone": ["<HASH>","<HASH>"], "email": ["<HASH>","<HASH>"]}, 
    currency: "USD", 
    value: 16,
    event_name: "Purchase",
    event_time: 1456870902,
    custom_data: {
      product_category: "ICECREAM",
    },
  },
]

然后使用 custom_data.{YOUR_CUSTOM_PARAM} 创建自定义转化事件规则：

curl \
  -F 'name=Ice Cream Purchasers' \
  -F 'custom_event_type=Purchase' \
  -F 'event_source_id=<OFFLINE_EVENT_SET_ID>' \
  -F 'rule={"and": [{"event_name":{"eq":"Purchase"}},{"custom_data.product_category":{"i_contains":"ICECREAM"}}]}' \
  -F 'access_token=<ACCESS_TOKEN>' \

"https://graph.facebook.com/<API_VERSION>/act_<ACCOUNT_ID>/customconversions"

适用于合作伙伴的线下转化

要将线下转化事件归因于客户的广告，请按照下列步骤操作。在下列大部分步骤中，API 调用命令与用户管理自己的线下事件集和营销活动时调用的 API 命令一样。

1. 合作伙伴 - 创建线下事件集
2. 合作伙伴 - 与客户的商务管理平台共享事件集
3. 客户 - 分配广告账户的线下追踪权限
4. 客户 - 为广告设置线下追踪功能
5. 合作伙伴 - 上传线下事件，查看统计数据
6. 合作伙伴 - 为客户提供广告成效分析

这些步骤根据客户广告账户的合作伙伴或经销商权限设置而异：

• 您可能拥有客户的所有广告账户、事件集或其他任何资产。
• 您可能拥有对客户资产执行特定操作的权限。

如要设置这些权限，请参阅商务管理平台资产。

合作伙伴 - 共享事件集

与客户的商务管理平台共享事件集。然后客户可以使用该事件集追踪广告。

GET /<OFFLINE_EVENT_SET_ID>/agencies HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/agencies

参数

客户 - 分配广告账户的线下追踪权限

与客户共享合作伙伴创建的线下事件集。您必须是商务管理平台管理员或创建线下事件集的管理员级系统用户，才能为广告账户下的广告启用追踪功能。如果您是与线下事件集关联的广告账户的管理员，也可以执行此操作。如要调用此 API，发出调用命令的企业必须有权访问线下事件集。

您可通过此调用为广告账户分配线下事件的追踪和查看权限：

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

参数

提供外部编号

在某些情况下，您可能需要提供自己的外部编号来代表客户，并将这些编号与用户匹配。如要执行此操作，您可以根据下列指南使用 extern_id。

执行匹配流程的数据合作伙伴可以使用合作伙伴编号作为命名空间编号，并使用 extern_id 作为您的 tpid。

仅提供 match_keys

我们会使用 match_keys 尝试确定您所分享的转化数据能否与 Meta 用户相匹配。如果您提供 match_keys，则不能同时提供 namespace_id 参数。

同时提供 match_keys 和 extern_id

我们会使用 match_keys 尝试查找 Meta 用户，并将映射条目从 {dataset_id, extern_id} 转发至 {facebook_user_id}。如果您提供 match_keys 和 extern_id，则不能同时提供 namespace_id。

仅提供 extern_id

如果您已发送包含 match_keys 和 extern_id 的数据，Meta 会使用 {dataset_id, extern_id} 检索 {facebook_user_id}。

提供 namespace_id

namespace_id 参数适用于整个 API 调用。您可以使用此参数指向某个商务管理平台或合作伙伴个人主页编号可访问或拥有的其他线下事件集。如果您已发送包含 match_keys 和 extern_id 的数据，Meta 会使用 {namespace_id, extern_id} 检索 {facebook_user_id}。每行数据只应提供一个 extern_id。

成效分析和归因

查看归因于用户所查看或点击广告的线下事件。我们会在超过 1 天后统计线下转化。这意味着您需要将统计时间窗设置为 28d_view 或 action_attribution_windows=['28d_view']'，否则无法在报告中看到任何转化事件。请参阅成效分析 API 和成效分析指南。

GET /act_<ADACCOUNT_ID>/insights HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/act_<ADACCOUNT_ID>/insights

参数

结果如下所示：

{
  "data": [
    {
      "date_start": "2015-12-01",
      "date_stop": "2015-12-01",
      "actions": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
          "action_type": "offsite_conversion.lead",
          "value": 3
        },
      ],
      ...
    }
  ]
}

例如，查看归因数据：

curl -G \
  -d 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  -d 'fields=unique_actions,action_values' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/insights

结果如下所示：

{
  "data": [
    {
      "unique_actions": [
        {
          "action_type": "link_click",
          "value": 94
        },
        {
          "action_type": "offline_conversion",
          "value": 1
        },
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
....
          "value": 1
        }
      ],
      "action_values": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 27.5
        },
        {
          "action_type": "offline_conversion",
          "value": 27.5
        }
      ],
      "date_start": "2016-06-06",
      "date_stop": "2016-06-07"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

适用于美国用户的数据处理选项

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": []
        }
    ]
}

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>",
                "client_ip_address": "256.256.256.256"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 0,
            "data_processing_options_state": 0
        }
    ]
}

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 1,
            "data_processing_options_state": 1000
        }
    ]
}

详细了解数据处理选项。