线下事件设置指南
快速入门
本指南介绍了使用事件 API 2.0 设置线下事件的流程。 - 如果您想新建一个线下事件组，请从第一步开始。 - 如果您想使用现有的线下事件组，可以从第二步开始。
1. 创建线下事件组
方法 1：通过事件管理平台 UI
a. 在 TikTok 广告管理平台中，导航到工具 > 事件。
b. 点击关联数据来源 > 线下。
c. 输入线下事件组名称并选择“创建”。
d. 打开自动监测功能：此广告账户今后的所有推广系列都会将该线下事件组用于广告监测和归因。
e. 创建线下事件组后，记录线下事件组 ID（该 ID 将用作通过事件 API 发送线下事件的event_source_id）。
方法 2：通过 API
您可以使用/offline/create/创建一个线下事件组。
请求
地址 https://business-api.tiktok.com/open_api/v1.3/offline/create/
方法 POST
Header
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。<br><br>若想获取访问令牌，请查看[事件 API 2.0 - 获取访问令牌](1771101130925058.html)。|
|Content-Type {必填}|string|请求信息类型。<br><br>允许格式：`application/json`。|
参数
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|---|
|advertiser_id {必填}|string|广告主ID。|
|name{必填}|string|线下事件组名称。<br><br>示例：`"in_store_purchases"`。|
|description|string|线下事件组描述。<br><br>示例：`"in_store_purchases_blackfriday"`。|
|auto_tracking|boolean|是否开启自动监测。<br><br>如果本字段设置为`true`，今后在本广告主账户下新建的所有推广系列都会将该事件组用于广告监测和归因。<br><br>枚举值：`true`，`false`。|
示例
注意
您需要将示例中的虚拟数据替换为自己的真实数据。
(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/offline/create/' \
--header 'Access-Token: {{Access-Token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"advertiser_id": "123456",
"name": "EVENT_SET_NAME",
"description": "In_store_purchases_blackfriday_2021",
"auto_tracking": true
}'
(/code)
返回
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|code |number| 返回码。完整返回码列表及描述，参见 [附录 - 返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|message |string| 返回信息。更多信息参见 [附录 - 返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。 |
|request_id |string| 请求的日志ID，唯一标识一个请求。 |
|data |object| 返回数据。<br><br>若请求成功，本字段将返回空对象（`{}`）。<br>若请求失败，将不返回本字段。 |
#|event_set_id| string | 您刚创建的线下事件组的ID。|
示例
(code)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"event_set_id": "{{event_set_id}}"
}
}
(/code)
2. 生成访问令牌
要验证事件 API 调用，您需要一个访问令牌。若想了解如何生成访问令牌，请查看事件 API 2.0 > 获取访问令牌。
通过事件 API 2.0 发送线下事件
- 在线下事件组中上传线下事件 线下事件组创建完成后，您需在事件组中上传线下事件，即顾客在线下达成某一业务目标的行为。若想了解支持的线下事件，请查看支持的事件 - 线下标准事件。
请注意，您还可以在事件管理平台通过文件向线下事件事件组中上传线下事件。
- 使用推荐的有效负载格式。
报告线下事件的参数
每个参数支持的格式参见下表。
顶层参数
|字段{25%}|类型{15%}|描述{60%}|
|---|---|---|
| event_source {必填} | string | 本字段用于指定通过事件 API 上传的事件类型。<br><br>枚举值：<ul><li> `offline`：在实体店铺中发生的转化事件，通过线下事件组 ID 追踪。</li></ul> |
| event_source_id {必填} | string | 用于追踪事件的事件源 ID。<br><br> <ul><li>当`event_source`设置为`offline`时，需通过本字段指定线下事件组 ID。 <br>若要获取线下事件组 ID，请查看[线下事件设置指南](1771101027431425.html)。</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)。 |
#| event_time{必填} | integer | <strong>网站事件、应用事件和线下事件均需指定本字段。</strong><br><br>事件发生的时间，以 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-ad参数"> `user`参数</a>"小节。 |
#| properties | object | 有关产品和订单信息和其他附加信息，可用于优化广告表现。 <br><br>若想查看`properties`对象中包含的字段，请查看下文的" <a href="#item-link-properties参数"> `properties`参数</a>"小节。 |
- 线下事件的
event_source_id是您想要发送事件的线下事件组的 ID。您可以通过导航到工具 > 事件 > 数据来源按钮来获取线下事件组的 ID。
user参数
|字段{25%}|类型{15%}|描述{60%}|
|---|---|---|
| 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%}|类型{15%}|描述{60%}|
|---|---|---|
|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%}|类型{15%}|描述{60%}|
|---|---|---|
| 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 | 商品的品牌名称。 |
请注意，您还可以在事件管理平台通过文件向线下事件组中上传线下事件。
示例
(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": "offline",
"event_source_id": "{{Offline-Event-Set-ID}}",
"data": [
{
"event_id":"1616318632825_357",
"event": "Purchaset",
"event_time": 1684574395,
"user": {
"email": ["848a771458438fc2ec420560d769fb9b9b86851ee338ec56517baabd79d3bb4f",
"dd6ff77f54e2106661089bae4d40cdb600979bf7edc9eb65c0942ba55c7c2d7f"],
"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
}
}
]
}'
(/code)
验证线下事件设置
若想了解验证线下事件设置的最佳实践，请查看验证事件 API 设置。
管理线下事件组（可选）
您可通过以下方式管理线下事件组： - 使用/offline/update/更新线下事件组的名称或自动监测设置。 - 使用/offline/delete/删除线下事件组。 - 使用/offline/get/获取广告账户下的线下事件组列表。
在普通广告或程序化创意广告中追踪线下事件组
若要在广告中追踪线下事件组，需在调用/ad/create/或/ad/aco/create/时指定tracking_offline_event_set_ids参数。需注意单个广告中最多传入50个线下事件组，其中最多包含10个开启自动监测的线下事件组。