← 返回目录
📁 Marketing API › Ad Measurement › Guides › Events API 1.0

事件 API：应用事件

注意
事件API - 应用事件目前处于测试阶段。如果需要使用本组接口，请联系您的TikTok销售代表。在您的账户进入白名单后，您才可以使用 /v1.3/app/track/ 或 /v1.3/app/batch/ 报告事件。

概览

TikTok 事件API是一种服务器到服务器的集成，支持广告主直接与TikTok分享网页事件，应用事件和线下事件。事件API与其他TikTok数据集成业务工具（如TikTok Pixel和TikTok SDK）具有类似的数据分享流程。您可以根据共享的数据，使用事件API赋能其他TikTok解决方案，如动态展示广告、自定义定向、推广系列优化和归因。

优势

  1. 高效率的稳定性和安全性： 快速集成和迭代，不受客户端局限性（例如网络连接问题或广告拦截器）的影响。
  2. 可配置的隐私控制： 通过隐私控制，灵活设置共享的事件和时间。
  3. 最大化的事件衡量： 在不同的浏览器、应用程序和设备上准确捕获更多事件，形成用户历程（从页面浏览到完成购买）的统一视图。

注意事项

  • 我们希望广告主遵守iOS14中对于隐私和用户数据的准则。
  • 目前本组接口不支持报告定制事件或报告个人身份信息。如果需要报告未支持的的应用事件，请与你的TikTok销售代表联系。
  • 一个请求仅向一个移动应用ID报告事件。设置此限制主要是因为授权会在用户/移动应用层面进行。
  • 未来QPS支持能力：每接口每开发者应用高达1k（TikTok API for Business 应用）。如需更高QPS支持能力，请联系PSO/解决方案工程师。
  • 如果需要报告单个事件，请向/app/track/接口发送POST请求。如果需要批量报告应用事件，请使用/app/batch/接口。

流程概览

要通过TikTok API for Business报告应用事件，广告主需要经过以下流程（假设您已经在 TikTok 上使用一个或多个 TikTok 广告账户投放广告）：

  1. 首先，您需要注册为 TikTok 广告开发者（参阅注册成为开发者）并创建一个TikTok API for Business开发者应用（参阅创建开发者应用）。

  2. 在推广您的移动应用的广告账户中，在 TikTok 广告管理平台 > 工具 > 事件 > 关联数据来源 > 应用 中创建移动应用，然后选择“我不使用移动监测合作伙伴服务”。

  3. 成功创建移动应用后，您可以点进详情找到对应的 TikTok 应用 ID。参考商务帮助中心。

TikTok 应用 ID

  1. 创建一个 TikTok 开发者应用，并授予“评估 > 报告应用事件”权限。

  2. 创建开发者应用后，使用第 2 步所用的系统用户的身份，在浏览器中打开已授权的 URL，并确认向 TikTok 开发者应用授予报告事件的权限，从而向此用户有权限（用户级权限）的所有移动应用报告事件。

  • 生成此访问令牌时，建议仅授予“报告应用事件”权限。即便访问令牌遭到泄露，也可以将影响降至最低。

  1. 使用授权代码换取访问令牌（参阅OAuth授权）并妥善保存访问令牌。

  2. 在您的TikTok API for Business请求中使用访问令牌进行验证，以便向TikTok发送应用事件。

报告单个应用事件

您可以使用本接口向 TikTok 报告移动（即 Android/iOS 系统）应用事件（例如：启动应用、购买）。

请求

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

方法 POST

Header

|字段|类型|描述|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
|Content-Type {必填}|string|请求信息类型<br>允许格式：`application/json`。|

参数

|字段|类型|描述|
|---|---|---|
|tiktok_app_id {必填}|string|TikTok App ID, TikTok平台绑定移动应用的唯一代码。你可以在TikTok Ads Manager里为移动应用生成TikTok App ID。更多细节，请参考[TikTok App ID](https://ads.tiktok.com/help/article?aid=10001060)。|
|event |string|应用事件名。示例值：`INSTALLAPP`、`PURCHASE`。支持的应用事件请查看[应用事件类型](https://ads.tiktok.com/marketing_api/docs?id=1739585574120449)中表格内的<strong>用于事件追踪的事件名</strong>列。|
|timestamp|string|采用 ISO 8601 格式的时间戳。详见 [wiki](https://en.wikipedia.org/wiki/ISO_8601).|
|context  {必填} |object|有关广告跟踪的信息，采用 JSON 格式。详见下文的<strong>context对象</strong>部分。|
|properties |object|与事件关联的属性，采用 JSON 格式。详见下文的<strong>properties对象</strong>部分。|

Context对象

|字段|类型|描述|
|---|---|---|
|context {必填}|object|有关广告跟踪的信息，采用 JSON 格式。|
#|app {必填}|object|有关要报告事件的应用的详细信息。|
##|id {必填}|string|<p>移动应用 ID。</p><p>例如（粗体部分）应用商店：https://apps.apple.com/us/app/angry-birds/id<b>343200656</b>；Google Play：https://play.google.com/store/apps/details?id=<b>com.rovio.angrybirds</b>。</p>如果是 Google Play 商店不提供的 Android 应用，请使用应用包名。|
##|name |string|应用名|
##|namespace |string|Android 应用包名或 iOS Bundle ID。示例值：com.rovio.baba|
##|version |string|应用版本号。示例值：3.0.2|
##|build |string|应用构建号。示例值：122|
#|device |object|此数据用于报告设备级数据以匹配用户。idfa/idfv/advertising_id 如果可获取，则必须填写。iOS：idfa/idfv；Android：advertising_id。|
##|platform |string|用户设备的操作系统；目前仅支持 iOS/Android|
##|idfa |string|iOS  IDFA (广告主标识符)。如果是 iOS14 或更高版本，请确保 IDFA 数据收集遵循 [Apple 政策](https://developer.apple.com/app-store/user-privacy-and-data-use/).<br>IDFA原值及IDFA的SHA256加密值均支持，但需注意：<ul><li>   对于IDFA原值，所有字符均需<strong>大写</strong>。对于IDFA的SHA256加密值，所有字符均需<strong>小写</strong>。示例：<ul><li>   IDFA原值："EA7583CD-A667-48BC-B806-42ECB2B48606"</li><li>     IDFA的SHA256加密值："70574fa9c8f498a7b2e5c8712b1126de7b1406fd02fdc591821c5bd33092fd1c"</li></ul></li><li>   进行SHA256加密前需去掉首尾空格。</li></ul>|
##|idfv |string|iOS IDFV (应用开发商标识符)。|
##|gaid |string|GAID（谷歌广告ID）。<br>GAID原值及GAID的SHA256加密值均支持，但需注意：<ul><li>   对于GAID原值及GAID的SHA256加密值, 所有字符均需<strong>小写</strong>。示例： <ul><li>       GAID原值："aaaaaa-2222-1111-8787-809e92233ba0"</li><li>       GAID的SHA256加密值： "0ebad966881e1eebffe69b3abf624631cf83ec9bf8cb3ce134c7c75c6d8ee7fc"</li></ul></li><li> 进行SHA256加密前需去掉首尾空格。</li></ul>|
##|att_status |string|用户的应用追踪权限。即用户是否授权给你的应用访问应用相关数据来追踪用户和其设备。这是iOS独有字段。可选值：<ul><li>`AUTHORIZED`：用户授权应用相关数据被用来追踪用户和其设备。</li><li>`DENIED`：用户拒绝给你的应用授权访问应用相关数据来追踪用户和设备。当设为此值时，TikTok将不会用这次事件里的PII数据（例如用户邮箱/手机号）来做用户层级追踪。</li><li>`NOT_DETERMINED`：当用户还没收到授权请求允许访问应用相关数据来追踪用户及其设备，使用此值。</li><li>`RESTRICTED`：追踪用户及其设备的应用相关数据的授权处于限制状态。</li><li>`NOT_APPLICABLE`：iOS版本低于14或Android设备，使用此值</li></ul>|
#|locale |string|取值：https://tools.ietf.org/rfc/bcp/bcp47.txt.示例值：zh-CN、en-US|
#|ip |string|用户 IP|
#|user_agent |string|来自用户设备的用户代理。示例值：Mozilla/5.0（iPhone；CPU iPhone OS 11_0，如 Mac OS X）AppleWebKit/604.1.38（KHTML，如 Gecko）Version/11.0 Mobile/15A372 Safari/604.1|
#|user |object|用户的个人数据。|
##|external_id |string|外部用户id<p>必须在客户端用SHA256加密。开头结尾空格需要在加密前去除。|
##|phone_number |string|用户的电话号码<p>必须在客户端用SHA256加密。<p>- 如果国家代码为+86，需要省略。（例：13800000000）<p>- 否则，需添加包含'+'的国家代码，且去掉空格以及其他所有号码间字符(空格，'-')。以US为例：+12133734253<p>然后用SHA256加密。<p>参考文档：[https://github.com/google/libphonenumber](https://github.com/google/libphonenumber)|
##|email |string|用户的email地址<p>必须在客户端用SHA256加密。需要在加密前统一使用小写字母。|
#|library |object|SDK版本信息。|
##|name |string|SDK版本名，例如：bytedance/tiktok-business-android-sdk|
##|version |string|SDK版本号，例如：1.2.0|
#|ori_attribution_partner|string|如果事件被MMP归因到其他平台，用此字段来代表平台名。例如,"facebook", "google"|
#|ad|object|广告信息|
##|callback|string|回调信息，用于帮助事件归因|
##|campaign_id|string|推广系列ID|
##|ad_id|string| 广告组 ID|
##|creative_id|string|广告ID|
##|isRetargeting|boolean|用户是否是重定向（二次营销）客户|
##|attributed|boolean|事件是否已归因|
##|attributionType|string|归因类型|
##|attribution_provider|string|归因服务提供商|
#|location|object|用户的地点信息|
##|country|string|国家或地区|
##|city|string|城市|

Properties对象

与事件关联的属性，采用 JSON 格式。某些属性可能仅与特定的应用事件相关联。

|字段|类型|描述|
|---|---|---|
|properties|object|与事件关联的属性，采用 JSON 格式。|
#|contents |object[]|应用事件中的相关商品（例如：购买事件中购买的商品）|
##|price |double|商品价格|
##|quantity |number|商品数量|
##|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>|
##|content_id |string|商品在系统中的 ID|
##|brand|string| 商品的品牌名称。|
#|currency |string|ISO 4217 代码。示例值：EUR、USD、JPY|
#|value |double|订单或所售商品的总价值|
#|description |string|描述应用事件的字符串|
#|query |string|被搜索的文本字符串。|

示例

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/app/track/' \
--header 'Content-Type: application/json' \
--header 'Access-Token: {{Access-Token}}' \
--data-raw \
'{
  "tiktok_app_id": "{{TIKTOK-APP-ID}}",
  "event":"AddToCart",
  "timestamp":"2023-09-17T19:49:27Z",
  "context":{
    "app":{
      "id":"1211123727",
      "name":"Angry Birds Classic",
      "namespace":"com.rovio.baba",
      "version":"3.0.2",
      "build":"122"
    },
    "device":{
      "att_status":"AUTHORIZED",
      "platform":"iOS",
      "idfa":"30255BCE-4CDA-4F62-91DC-4758FDFF8512"
    },
    "locale":"zh-CN",
    "user":{
      "email":"12346a405862e402eb76a70f8a26fc732d07c32931e9fae9ab1582911d2e8a3b",
      "phone_number":"12346a405862e402eb76a70f8a26fc732d07c32931e9fae9ab1582911d2e8a3b"
    },
    "library":{
      "name":"1.1.0-alpha.1",
      "version":"2"
    },
    "ad":{
      "callback":"E.C.P.ExampleCallback",
      "isRetargeting":false,
      "campaign_id":"1700817380525057",
      "attributed":true,
      "ad_id":"1700817380806706",
      "attributionType":"click_through",
      "creative_id":"1700817378256945",
      "attribution_provider":"mmp"
    }
  },
  "properties":{
    "currency":"USD",
    "value":10,
    "contents": [
      {
        "quantity":5,
        "price":9.9
      }
    ]
  }
}'
(/code)

返回

|字段|类型|描述|
|---|---|---|
|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|返回数据|

示例

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "message": "OK",
    "code": 0,
    "request_id": "2019091810032301011023224213558"
}
(/code);

批量报告应用事件

您可以使用本接口批量报告应用事件。一个请求最多可报告 1000 个事件。如果一个请求包含 1000 个以上事件，则整个请求会被拒绝。

请求

地址: https://business-api.tiktok.com/open_api/v1.3/app/batch/

方法 POST

Header

|字段|类型|描述|
|---|---|---|
|Access-Token {必填}|string|已授权的访问令牌。可通过 <br>[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162) 接口获取。|
|Content-Type {必填}|string|请求信息类型<br>允许格式：`""application/json""`|

参数

|字段|类型|描述|
|---|---|---|
|tiktok_app_id {必填}|string|TikTok App ID, TikTok平台绑定移动应用的唯一代码。你可以在TikTok Ads Manager里为移动应用生成TikTok App ID。更多细节，请参考[TikTok应用ID](https://ads.tiktok.com/help/article?aid=10001060)。|
|batch |object[]|批量报告的一系列应用事件。长度必须大于 1 且小于 50。|
#|type |string|目前仅支持 track|
#|event |string|应用事件名。示例值：`INSTALLAPP`、`PURCHASE`。支持的应用事件请查看[应用事件类型](https://ads.tiktok.com/marketing_api/docs?id=1739585574120449)中表格内的<strong>用于事件追踪的事件名</strong>列。|
#|timestamp |string|采用 ISO 8601 格式的时间戳。详见 [wiki](https://en.wikipedia.org/wiki/ISO_8601).|
#|context {必填} |object|有关广告跟踪的信息，采用 JSON 格式。详见下文的<strong>context对象</strong>部分。|
#|properties |object|与事件关联的属性，采用 JSON 格式。详见下文的<strong>properties对象</strong>部分。|

示例

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/app/batch/' \
--header 'Content-Type: application/json' \
--header 'Access-Token: {{Access-Token}}' \
--data-raw \
'{
  "tiktok_app_id":"{{TIKTOK-APP-ID}}",
  "batch":[
    {
      "type":"track",
      "event":"InstallApp",
      "timestamp":"2023-09-17T19:49:27Z",
      "context":{
        "app":{
          "id":"com.rovio.angrybirds"
        },
        "user":{
          "email":"12346a405862e402eb76a70f8a26fc732d07c32931e9fae9ab1582911d2e8a3b"
        },
        "device":{
          "att_status":"AUTHORIZED",
          "platform":"iOS",
          "idfa":"30255BCE-4CDA-4F62-91DC-4758FDFF8512"
        },
        "ad":{
          "callback":"E.C.P.ExampleCallback"
        }
      }
    },
    {
      "type":"track",
      "event":"Purchase",
      "timestamp":"2023-09-17T20:00:00Z",
      "context":{
        "app":{
          "id":"com.rovio.angrybirds"
        },
        "user":{
          "email":"12346a405862e402eb76a70f8a26fc732d07c32931e9fae9ab1582911d2e8a3b"
        },
        "device":{
          "att_status":"AUTHORIZED",
          "platform":"iOS",
          "idfa":"30255BCE-4CDA-4F62-91DC-4758FDFF8512"
        },
        "ad":{
          "callback":"E.C.P.ExampleCallback"
        }
      }
    }
  ]
}'
(/code)

返回

|字段|类型|描述|
|---|---|---|
|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|返回数据|
#|partial_failure|boolean|报告应用事件是否部分失败|
#|failed_events|object[]|若部分失败，返回错误列表|
##|order_in_batch|number|批量请求订单|
##|error|string|错误信息|

示例

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "message": "OK",
    "code": 0,
    "request_id": "2019091810032301011023224213558"
}
(/code)

(code Failure http)
{
    "code": 40000,
    "message": "The value:{'aa'} is invalid for the associated parameter email.",
    "request_id": "2021012904054301023125302028613"
}
(/code)

(code Partial-Failure http)
{
    "code": 20001,
    "message": "Partial success. Correct entries are forwarded while incorrect ones are dropped.",
    "request_id": "2021012904061701023125302030787",
    "data": {
        "partial_failure": true,
        "failed_events": [
            {
                "order_in_batch": 0,
                "error": "unhashed email"
            }
        ]
    }
}
(/code)
← 事件 API 1.0事件 API：网站事件 →

内容来源：TikTok API for Business 官方文档 · 本地归档

在接这个接口时卡住了？
Stuck wiring this API into production? We build ad-delivery tooling on these platforms — campaign automation, reporting pipelines, error-handling and migration between API versions.
联系我们 · Talk to us 每日平台更新简报 →