应用事件设置指南
注意
使用事件 API 2.0 报告应用事件目前为白名单功能。如需使用此功能，请联系您的 TikTok 销售代表。
本指南介绍了使用事件 API 2.0 设置应用事件的流程。
创建应用并生成您的 TikTok 应用 ID
这些步骤需要在由具有管理员或操作员角色的用户在您的广告管理平台账户中执行。
访问事件管理平台
若要开始创建应用，请在 TikTok 广告管理平台账户中导航至工具 ➤ 事件。
创建您的应用
- 若您尚未设置数据连接，请选择"立即开始"。
- 若您已经设置了其他数据连接，请选择"关联数据来源"。
选择"应用"并继续。
提供您的应用详情
填写您的应用下载 URL 并继续。将自动填充应用图标、应用名称和应用 ID。
选择"使用 TikTok 事件 API"并继续。
随后应用创建完成，您将看到一些为您的应用推荐的事件。推荐基于特定垂类生成。记下这些内容后，点击完成进入应用详情页面。
生成您的 TikTok 应用 ID
记下您的应用 ID，并复制您的 TikTok 应用 ID。集成时需要这两个 ID。
您的应用 ID 将采用 App Store 或 Play Store URL 中常用的反向 DNS 格式（Android）或短数字字符串（iOS）格式。您的 TikTok 应用 ID 是一个较长的数字字符串，随具体的广告账户变化。
生成访问令牌
要验证事件 API 调用，您需要一个访问令牌。您可以在“设置”选项卡中生成一个访问令牌。若想了解如何生成访问令牌，请查看事件 API 2.0 - 获取访问令牌。
报告应用事件
您可以使用事件 API 2.0 接口 /event/track/ 向 TikTok 报告（Android 或 iOS 系统的）移动应用事件（例如LaunchAPP或Purchase）。
地址 https://business-api.tiktok.com/open_api/v1.3/event/track/
方法 POST
Header
|字段{30%}|类型{15%}|描述{70%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。<br><br>若想获取访问令牌，请查看[事件 API 2.0 - 获取访问令牌](1771101130925058.html)。|
|Content-Type {必填}|string|请求信息类型。<br><br>允许格式：`application/json`。|
报告应用事件的参数
注意
若想获取 cURL、Python 和 Node.js 格式的代码示例，从而通过事件 API 2.0 报告应用事件，可使用应用事件的有效负载助手。
顶层参数
|字段{25%}|类型{15%}|描述{60%}|
|---|---|---|
| event_source {必填} | string | 本字段用于指定通过事件 API 上传的事件类型。<br><br>枚举值：<ul><li>`app`：在您的应用程序上发生的事件，通过 TikTok 应用 ID 追踪。</li></ul><br><p><span style="color:darkred"><b>注意</b></span>：使用事件 API 2.0 报告应用事件目前为白名单功能。如需使用此功能，请联系您的TikTok销售代表。 |
| event_source_id {必填} | string | 用于追踪事件的事件源 ID。<br><br> <ul><li>当`event_source`设置为`app`时，需通过本字段指定 TikTok 应用 ID。 <br>若要获取 TikTok 应用 ID，请查看[应用事件设置指南](1771101111730178.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)。<br>若您要报告自定义事件，您需通过本字段传入一个自定义名称。 |
#| event_time{必填} | integer | 事件发生的时间，以 Unix 时间戳表示，以秒为单位，对应时区为 UTC+0 。 |
#| user | object | 有关客户的信息。<br><br> 若想查看`user`对象中包含的字段，请查看下文的" <a href="#item-link-ad参数"> `user`参数</a>"小节。 |
#| properties | object | 有关产品和订单信息和其他附加信息，可用于优化广告表现。 <br><br>若想查看`properties`对象中包含的字段，请查看下文的" <a href="#item-link-properties参数"> `properties`参数</a>"小节。 |
#| app {必填} | object | 有关应用的信息。<br><br>若想查看`app`对象中包含的字段，请查看下文的" <a href="#item-link-app参数"> `app`参数</a>"小节。 <br><br><p><span style="color:darkred"><b>注意</b></span>：使用事件 API 2.0 报告应用事件目前为白名单功能。如需使用此功能，请联系您的TikTok销售代表。 |
#| ad | object | 有关广告的信息。<br><br>若想查看`ad`对象中包含的字段，请查看下文的" <a href="#item-link-ad参数">`ad`参数 </a>"小节。 |
#| limited_data_use | boolean | 若想要了解有关限制数据使用功能的更多信息，请查看[事件 API 2.0 - 限制数据使用](1771101204435970.html)。 |
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> |
| idfa | string | iOS IDFA（广告主标识符），<strong>仅应用事件可传入本字段。</strong><br><br>对于 iOS 14 及以上版本，请确保 IDFA 数据收集遵循 [Apple 的政策](https://developer.apple.com/app-store/user-privacy-and-data-use/)。<br><br>允许传入未经 SHA-256 散列处理或经SHA-256 散列处理的 IDFA： <ul><li>对于未经 SHA-256 散列处理的 IDFA，所有字符必须为<strong>大写</strong>。</li><li>对于经SHA-256 散列处理的 IDFA，所有字符必须为<strong>小写</strong>，且散列处理前需<strong>去掉首尾空格</strong>。 </li></ul> |
| idfv | string | iOS IDFV（应用开发商标识符），<strong>仅应用事件可传入本字段。</strong>|
| gaid | string | GAID（谷歌广告 ID），<strong>仅应用事件可传入本字段。 </strong><br><br>允许传入未经 SHA-256 散列处理或经SHA-256 散列处理的 GAID。<br>对于未经 SHA-256 散列处理或经SHA-256 散列处理的 GAID：<ul><li>所有字符必须为<strong>小写</strong>，且 </li><li>散列处理前需去掉<strong>首尾空格</strong>。</li></ul>|
| ip | string | 用户设备的未经散列处理的公共 IP 地址。<br><br>为增加网站访客事件与 TikTok 广告的匹配率，建议同时传入 `ip` 和 `user_agent`。 |
| user_agent | string | 用户设备的未经散列处理的用户代理。<br><br>为增加网站访客事件与 TikTok 广告的匹配率，建议同时传入 `ip` 和 `user_agent`。 |
| locale | string | BCP 47 语言标识符。<br><br>若想了解该标识符的详情，请查看[IETF BCP 47 标准语言代码](https://www.rfc-editor.org/rfc/bcp/bcp47.txt)。 |
| att_status | string | 用户的应用追踪权限。即用户是否授予您的应用访问应用相关数据的权限，以追踪用户及其设备。这是 iOS 独有字段。<br><br>枚举值：<ul><li> `AUTHORIZED`：用户已授权访问可用于追踪用户及其设备的应用相关数据。</li><li>`DENIED`：用户尚未通过 [Apple 的 AppTrackingTransparency 框架](https://developer.apple.com/documentation/apptrackingtransparency)授权访问可用于追踪用户及其设备的应用相关数据。<br> 若设置为此值，TikTok 将不会将应用事件里的个人信息数据（例如用户电子邮件地址/手机号）用于用户追踪。</li><li>`NOT_DETERMINED`：用户尚未收到允许访问应用相关数据来追踪用户及其设备的授权请求。</li><li>`RESTRICTED`：追踪用户及其设备的应用相关数据的授权处于限制状态。</li><li> `NOT_APPLICABLE`：iOS 版本低于14 或正在使用 Android 设备。</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><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 | 商品或页面的描述。 |
|customer_type|string|用于表示与转化事件关联的客户细分群体的类别标签。<br><br>枚举值： <ul><li>`new`：新客户。</li><li>`returning`：老客户。</li></ul>|
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 | 商品的品牌名称。 |
app参数
|字段{25%}|类型{15%}|描述{60%}|
|---|---|---|
| app_id {必填} | string | 移动应用 ID。<ul><li>对于 iOS 应用，请使用在 App Store URL 中的应用 ID。<ul><li>示例：Apple Store URL：`https://apps.apple.com/us/app/angry-birds/id343200656`<ul><li> id = `"343200656"`</li></ul> </li></ul></li><li>对于在 Google Play 商店中的 Android 应用，请使用在 Google Play 商店 URL 中的应用 ID。<ul><li>示例：Google Play 商店 URL：`https://play.google.com/store/apps/details?id=com.rovio.angrybird`<ul><li> id = `"com.rovio.angrybirds"` </li></ul></li></ul></li><li>对于未在 Google Play 商店中的 Android 应用，请使用应用包名。</li></ul>|
| app_name | string | 应用名称。 |
| app_version | string | 应用版本号。<br><br> 示例：`"3.0.2"`。 |
ad参数
|字段{25%}|类型{15%}|描述{60%}|
|---|---|---|
| callback | string | 回调信息，用于帮助事件归因。 |
| campaign_id | string | 推广系列 ID。 |
| ad_id | string | 广告组 ID。 |
| creative_id | string | 广告 ID。 |
| is_retargeting | boolean | 用户是否是重定向（再营销）客户。 |
| attributed | boolean | 事件是否已归因。 |
| attribution_type | string | 归因类型。 |
| attribution_provider | string | 归因服务提供商。 |
|attribution_share|float| 归因份额分数。<br>你为每次转化打的分数，代表 TikTok 在促成转化方面应获得的贡献比例。分数越高，表明 TikTok 对转化的贡献越大。<br><br>示例：<ul><li>0.0：无贡献。</li><li>0.5：部分贡献。</li><li>1.0：全部贡献。</li></ul>|
有效负载示例
以下为报告一个Purchase 应用事件的请求示例。
(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": "app",
"event_source_id": "{{TIKTOK_APP_ID}}",
"data": [
{
"event": "InstallApp",
"event_time": 1687758765,
"user": {
"phone": "{{HASHED_PHONE}}",
"email": "{{HASHED_EMAIL}}",
"idfa": "{{IDFA}}",
"idfv": "{{IDFV}}",
"gaid": "{{GAID}}",
"att_status": "AUTHORIZED",
"locale": "en-US"
},
"app": {
"app_id": "com.test.flyingsneakers",
"app_name": "Flying Sneakers",
"app_version": "3.0.2"
},
"ad": {
"attributed": true,
"callback": "{{CALLBACK}}",
"campaign_id": "1700817380525057",
"ad_id": "1700817380806706",
"creative_id": "1700817378256945",
"is_retargeting": false,
"attribution_type": "click_through"
},
"properties": {
"currency": "USD",
"value": 200.0,
"content_type": "product",
"contents": [
{
"price": 100.0,
"quantity": 2,
"content_id": "12345",
"content_name": "Fancy-AirMax2.0 Black",
"content_category": "Shoes - Running Shoes",
"brand": "Fancy Sneakers"
}
]
}
}
]
}'
(/code)