CRM 事件设置指南

快速入门

本指南介绍了使用事件 API 2.0 设置 CRM（客户关系管理）事件的流程。 - 如果您希望创建一个新的 CRM 事件组，请从第一步开始。 - 如果您希望使用已有的 CRM 事件组，请直接从第二步开始。

1. 创建 CRM 事件组

a. 在 TikTok 广告管理平台中，导航至工具 > 事件。

工具 > 事件

b. 点击关联数据来源 > CRM。

关联数据来源 > CRM

c. 输入 CRM 事件组名称并选择创建。

d. 创建 CRM 事件组后，请记录 CRM 事件组 ID。该 ID 将在通过事件 API 发送 CRM 事件数据时用作 event_source_id。

2. 生成访问令牌

您需要访问令牌来授权调用事件 API。

若想了解如何获取访问令牌，请参考事件 API 2.0 > 获取访问令牌。

通过事件 API 2.0 发送 CRM 事件

在 CRM 事件组中上传 CRM 事件

CRM 事件组创建完成后，您需在事件组中上传 CRM 事件，即访客在您的 CRM 系统上为实现业务目标而采取的行为。

若想了解支持的 CRM 事件，请查看支持的事件 - CRM 标准事件。

使用推荐的事件有效负载格式。

地址 https://business-api.tiktok.com/open_api/v1.3/event/track/

方法 POST

Header

| 字段 {25%}| 数据类型 {10%}| 描述{65%} |
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。<br><br>若想获取访问令牌，请查看[事件 API 2.0 - 获取访问令牌](1771101130925058.html)。|
|Content-Type {必填}|string|请求信息类型。<br><br>允许格式：`application/json`。|

报告 CRM 事件的参数

每个参数值的格式请参考以下列表。

顶层参数

| 字段 {25%}| 数据类型 {10%}| 描述{65%} |
|---|---|---|
| event_source {必填} | string | 本字段用于指定通过事件 API 上传的事件类型。<br>允许的枚举值：<ul><li>`crm`：在 CRM 系统中发生的线索事件，通过 CRM 事件组 ID 追踪。</li></ul>|
| event_source_id {必填} | string | 用于追踪事件的事件源 ID。<br><br> <ul><li>当 `event_source` 设置为 `crm` 时，通过本字段指定 CRM 事件组 ID。 <br>要获取 CRM 事件组 ID，请参考<a href="#item-link-1. 创建 CRM 事件组">创建 CRM 事件组</a>或本表格下方的说明。</li></ul>|
| data{必填} | object[] | 您要报告的事件的对象数组。 <ul><li>若只发送单个事件，请在本对象数组中传递一个对象。</li><li>若要在单个有效负载中批量发送多个事件，则单个请求中的本对象数组最多可包含1,000个对象。</li><li>若单个请求中本对象数组的事件数超过1,000个，整个请求将被拒绝。为了优化广告活动的性能，<strong>强烈建议</strong>您一旦在服务器上捕捉到事件，便<strong>尽快以实时方式（即非批量方式）发送事件</strong>。</li></ul>|
#| event{必填} | string | 转化事件名称。 <br><br>支持的标准事件枚举值参见[事件 API 2.0 - 支持的事件](1771101186666498.html)。<br>若您要报告自定义事件，您需通过本字段传入一个自定义名称。 |
#| event_time{必填} | integer | 事件发生的时间，以 Unix 时间戳表示，以秒为单位，对应时区为 UTC+0 。 |
#| event_id {+条件必填} | string | 用于标识唯一事件的 ID ，允许使用允许使用经散列处理的值或未经散列处理的值。<br><br> 此 ID 可以用于在合作伙伴和TikTok之间进行数据匹配。<br><br> 我们建议使用32个字符的字符串，包括数字（0-9）、大写字母（A-Z）和小写字母（a-z）。 |
#| user | object |  有关客户的信息。<br><br> 若想查看`user`对象中包含的字段，请查看下文的"<a href="#item-link-user 参数">`user` 参数</a>"小节。 |
#| properties{+条件必填}  | object |  有关产品和订单信息和其他附加信息，可用于优化广告表现。 <br><br>若想查看`properties`对象中包含的字段，请查看下文的"<a href="#item-link-properties 参数">`properties` 参数</a>"小节。 |
#| lead | object | 有关线索的信息。 <br><br>若想查看`lead`对象中包含的字段，请查看下文的"<a href="#item-link-lead 参数">`lead` 参数</a>"小节。 |

CRM 事件的 event_source_id 是您要发送事件的 CRM 事件组的 ID。您可以通过导航到工具 > 事件 > 数据来源来获取 CRM 事件组的 ID。以下示例中 CRM 事件组的 ID 为 7446580941998374913。

CRM 事件组 ID

`user` 参数

| 字段 {25%}| 数据类型 {10%}| 描述{65%} |
|---|---|---|
| email | string 或 string[] | <strong>需传入经 SHA-256 散列处理的值。</strong><br><br>客户的单个或多个电子邮件地址。  <br><br> 按照以下说明获取有效值：<ul><li>在散列处理之前<strong>去除</strong>每个电子邮件地址<strong>首尾空格</strong>。</li><li>在散列处理之前将所有字符转换为<strong>小写</strong>。</li><li>随后使用 SHA-256 算法对预处理后的电子邮件地址值进行<strong>散列处理</strong>。 </li></ul><br><strong>示例</strong>： <ul><li>原始值：`" ALICE_abc@gmail.com "` </li><li>预处理后的值：`"alice_abc@gmail.com"`（去除首尾空格且字符转换为小写）</li><li> SHA-256 散列处理后的值：`"848a771458438fc2ec420560d769fb9b9b86851ee338ec56517baabd79d3bb4f"` </li></ul>|
| phone | string 或 string[] | <strong>需传入经 SHA-256 散列处理的值。</strong><br><br>客户的单个或多个电话号码。  <br><br>按照以下说明获取有效值：<ul><li>将电话号码<strong>预处理</strong>为 E.164 格式（例如，"+12133734253"）。建议使用 [https://github.com/catamphetamine/libphonenumber-js](https://github.com/catamphetamine/libphonenumber-js) 进行 E.164 解析。<ul><li>必须包含以 `+` 号为前缀的<strong>国家电话区号</strong>，无任何括号，且开头无`0`。例如，美国电话号码应以国家电话区号`+1`为前缀。</li><li>除了国家代码中的`+`号外<strong>不包括任何空格、字母或符号</strong>。</li></ul> </li><li>在预处理后对电话号码进行<strong> SHA-256 散列处理</strong>。</li></ul><br><br><strong>示例</strong>： <ul><li>原始值："(+1)2133734253"  </li><li>预处理为 E.164 格式："+12133734253"  </li><li> SHA-256 散列处理后的值："9f7ec22d72092cd3c0b58726ed9c2d91b92e51a3f29837508fb2948bb22dd2fd" </li></ul> |

`properties` 参数

| 字段 {25%}| 数据类型 {10%}| 描述{65%} |
|---|---|---|
|content_ids| string[]|商品或内容的唯一 ID 或多个 ID 的列表。 <br>示例：`["987","654"]`。 <br>推荐使用 `sku id` 或 `item_group_id`。若商品库中的商品设置了`sku_id`或`item_group_id`，则需保持一致。<br>本参数在视频购物广告场景为必填。 |
| contents| object[] | 事件中对应的有商品信息的商品。<br><br>若想查看`contents`对象中包含的字段，请查看下文的"<a href="#item-link-contents 参数"> `contents` 参数</a>"小节。  |
| content_type | string | 事件中内容的类型。 <br><br>枚举值：`product`（商品），`product_group`（商品组）。<br><br><ul><li>若`contents`参数中的`content_id`设置为`sku_id`，则本参数需设置为`product`。</li><li>若`contents`参数中的`content_id`设置`item_group_id`，则本参数需设置为 `product_group`。 </li></ul> |
| currency | string | 推荐为营收相关事件传入本字段。<br><br> ISO 4217 币种代码。<br><br>示例： `EUR`, `USD`, `JPY`。<br><br> 目前支持的币种清单： `AED`，`ARS`，`AUD`，`BDT`，`BHD`，`BIF`，`BOB`，`BRL`，`CAD`，`CHF`，`CLP`，`CNY`，`COP`，`CRC`，`CZK`，`DKK`，`DZD`，`EGP`，`EUR`，`GBP`，`GTQ`，`HKD`，`HNL`，`HUF`，`IDR`，`ILS`，`INR`，`ISK`，`JPY`，`KES`，`KHR`，`KRW`，`KWD`，`KZT`，`MAD`，`MOP`，`MXN`，`MYR`，`NGN`，`NIO`，`NOK`，`NZD`，`OMR`，`PEN`，`PHP`，`PHP`，`PKR`，`PLN`，`PYG`，`QAR`，`RON`，`RUB`，`SAR`，`SEK`，`SGD`，`THB`，`TRY`，`TWD`，`UAH`，`USD`，`VES`，`VND`，`ZAR`|
| value | float | 推荐为营收相关事件传入本字段。<br><br>订单或所售商品的价值。 <br><br>本字段值的格式需为整数或小数（例如10.00），无论地域、币种或其他因素。同时不允许包含币种符号，特殊字符，字母或逗号。 <br><p><span style="color:darkred"><b>注意</b></span>：`price`（价格）是单件商品的价格，而`value`（价值）是指订单的总价。例如，若您有两件商品，每件商品的销售价格是 10 美元，那么 `price` 参数需要设置为 `10.00`，`value`参数需要设置为`20.00`。 |
|num_items|integer| 商品数量。|
|search_string|string|用户输入的用于搜索的文本字符串。|
| description | string | 商品或页面的描述。 |
| order_id | string | 订单 ID。 |
| shop_id | string | 商店 ID。 |

`contents` 参数

| 字段 {25%}| 数据类型 {10%}| 描述{65%} |
|---|---|---|
| price | float | 商品价格。<br><br>示例：`10`，`10.5`。 <br><br><p><span style="color:darkred"><b>注意</b></span>：`price`（价格）是单件商品的价格，而`value`（价值）是指订单的总价。例如，若您有两件商品，每件商品的销售价格是 10 美元，那么 `price` 参数需要设置为 `10.00`，`value`参数需要设置为`20.00`。 |
| content_id  | string | 商品或内容的唯一ID。 <br><br>推荐使用 `sku_id` 或`item_group_id`。<br><br>若商品库中的商品设置了`sku_id`或`item_group_id`，则需保持一致。 |
| content_category | string | 页面或商品的类别。 |
| content_name | string | 页面或商品的名称。 |
| brand | string | 商品的品牌名称。 |

`lead` 参数

使用lead参数与事件 API 2.0 分享有关 CRM 系统中线索的信息。lead参数应仅在报告 CRM 事件（event_source = crm）时使用。

| 字段 {25%}| 数据类型 {10%}| 描述{65%} |
|---|---|
| lead_id {+条件必填} | string | <b>对于 CRM 事件必填。</b><br><br>TikTok 线索的 ID。<br> 从 TikTok 导出的线索均有对应的`lead_id`。<br> <br>若想获取线索 ID，可使用 [/page/lead/task/](1739052936772610.html) 和 [/page/lead/task/download/](1739053563877378.html) 接口下载线索，或从 TikTok 广告管理平台中的第一方 CRM 平台 Leads Center 导出线索。 |
| lead_event_source | string | 线索事件来源。<br>您可将本字段设置为您的 CRM 系统的名称，例如 HubSpot 或 Salesforce。 |

请注意，您还可以在事件管理平台通过文件向 CRM 事件组中上传 CRM 事件。

有效负载示例

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/event/track/' \
--header 'Access-Token: {{Access-Token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "event_source": "crm",
  "event_source_id": "{{CRM-Event-Set-ID}}",
  "data": [
    {
      "event_id":"1616318632825_357",
      "event": "Purchase",
      "event_time": 1684574395,
      "user": {
        "email": "848a771458438fc2ec420560d769fb9b9b86851ee338ec56517baabd79d3bb4f",
        "phone": "2f9d2b4df907e5c9a7b3434351b55700167b998a83dc479b825096486ffcf4ea"
       },
      "properties": {
        "order_id": "abc_xyz",
        "shop_id": "123abc",
        "contents": [
          {
            "price": 8,
            "quantity": 2,
            "content_id": "1077218",
            "content_name": "running shoes",
            "content_category": "Shoes > Sneakers > running shoes",
            "brand": "your_brand_name"
          },
          {
            "price": 30,
            "quantity": 1,
            "content_id": "1197218",
            "content_name": "running shoes",
            "content_category": "Shoes > Sneakers > running shoes",
            "brand": "your_brand_name"
          }
        ],
        "content_type": "product",
        "currency": "USD",
        "value": 46.00
      },
      "lead": {
        "lead_id": "71247185198338",
        "lead_event_source": "YourCRM"
      }
    }
  ]
}'
(/code)

验证 CRM 事件设置

若想了解验证 CRM 事件设置的最佳实践，请查看验证事件 API 设置。

（可选）管理 CRM 事件组

您可以通过以下方式管理 CRM 事件组： - 通过 /crm/list/ 获取广告账户下的 CRM 事件组列表。