以广告主身份获取线索

本文介绍了以广告主身份获取线索广告中线索数据的具体步骤。

简介

当您创建线索收集推广系列时，您可以增加转化量并提高网页访问量。线索收集能从对您业务感兴趣的受众那里收集有用的信息。您可以使用API，通过以下两种方式快速获取线索数据： * 下载线索 * 通过 Webhook 订阅线索

前提条件

您已经拥有 TikTok API for Business 的使用权限。详见快速入门 - 具体步骤。
若要通过 Webhook 订阅线索，您需要获取相关的权限。参阅 API 参考了解使用相关接口（包括“步骤”部分列出的接口）所需的权限；参阅更新应用权限范围了解如何设置权限。
您已创建线索广告。详细创建步骤见创建线索广告。

步骤

下载线索

注意
为了保护客户信息，只有广告账户管理员才有权创建及查询线索下载任务，或进行线索下载。 1. 向接口/page/lead/task/发送GET请求，创建一个线索下载任务。 2. 当任务状态为SUCCEED时，向接口/page/lead/task/download/发送GET请求，下载线索。

通过 Webhook 订阅线索

Webhook 使您能够将线索广告与您的 CRM（客户关系管理）系统相集成，从而获取即时表单线索和私信线索的实时更新。

创建订阅

若想了解如何订阅线索 Webhook，请查看订阅新线索。

测试订阅

完成订阅后，您可以按照以下步骤进行线索事件的端到端测试。请注意：您只能为每个页面创建一个测试线索。在创建一个新的测试线索之前，您必须删除现有的测试线索。

向接口/page/lead/mock/create/发送POST请求，创建一个测试线索。
向接口/page/lead/mock/get/发送GET请求，获取测试线索。
向接口/page/lead/mock/delete/发送POST请求，删除测试线索。

注意事项

验证有效负载

所有事件通知的有效负载都使用HMAC-SHA256签署，请求Header中的X-Open-Signature包含该签名。我们建议您验证有效负载。

以下是验证有效负载的方法：

使用有效负载和您应用程序的应用密钥生成一个HMAC-SHA256签名。

以下是如何生成签名的示例：

示例有效负载：

(code JSON JSON)
{
   "request_id":{{request_id}},"
   object":{{object}},
   "entry": [
    {
      "id": {{id}},
      "page_id":{{page_id}},
      "page_name":"hello_world",
      "campaign_id":{{campaign_id}},
      "campaign_name":"{{campaign_name}}",
      "adgroup_id":{{adgroup_id}},
      "adgroup_name":"{{adgroup_name}}",
      "ad_id":{{ad_id}},
      "ad_name":"{{ad_name}}",
      "create_time":{{create_time}},
      "changes": [
       
        {
          "field": "phone_number",
          "value": "{{phone_number}}"
        },

        {
          "field": "email",
          "value": "{{email}}"
        },
   
        {
          "field": "name",
          "value": "{{name}}"
        },
      ]
    }
  ],
  "time": {{time}}
}
(/code)

示例应用密钥： 5b5c09c880c9af2c69e39b18024f255d3****

将您的有效负载和应用程序的应用密钥输入到HMAC-SHA256加密函数中，您将得到一个编码的结果字符串。这个字符串就是您的签名，例如：48fa5d1c81597afc6d15bf5aa588f45df8f0b22d0c0d66d8a2977b368a3f****。

比较您的签名与Header中X-Open-Signature的签名。如果签名一致，则该有效负载是真实的。

请注意：我们使用escaped unicode的有效负载，用小写的十六进制数字生成签名。如果您只是针对解码后的字节进行计算，您会得到一个不同的签名。例如，字符串äöå应该被转换为\u00e4\u00f6\u00e5。

响应事件通知

您的接口应该使用200 OK HTTPS响应所有事件通知。

频率

事件通知将在汇总后批量发送，最大更新次数为1000次。由于无法保证批量处理，请您务必调整服务器，确保能够单独处理每个webhook。如果发送到您服务器的更新失败，API将立即重试，您需要在接下来的24小时内降低频率再尝试几次。您的服务器应该在这些情况下处理重复数据删除。未答复的响应将在24小时后失效。

订阅后操作

如果您不再需要订阅某个界面的线索，您可以取消订阅。您可以获得一个广告商的所有订阅。详情请见获取订阅信息和取消订阅。

获取表单订阅和线索下载日志

您可以使用接口/changelog/task/create/，获取订阅表单、取消订阅表单以及从表单下载线索等行为的操作日志。请使用下列数据字段设置。 * 将页面ID传入object_ids数组。 * 将object_type设置为INSTANT_FORM。 * 将operation_types设置为DOWNLOAD_LEADS, SUBSCRIBE_FORM, 和UNSUBSCRIBE_FORM。