← 返回目录
📁 API Reference › Events 1.0 › App Events

批量报告应用事件

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

重要提示
使用事件 API 接口代表您同意遵守TikTok 商业产品（数据）条款，并且不会与 TikTok 分享敏感数据。

v1.2与v1.3版本对比

以下表格概括了 v1.2与v1.3接口的变化。 ``xtable |变化内容{30%}|v1.2{35%}|v1.3{35%}| |---|---|---| |接口路径| /v1.2/app/batch/| /v1.3/app/batch/| |请求参数类型|tiktok_app_id: number <br>campaign_id(in Context object): number <br>ad_id(in Context object): number <br>creative_id(in Context object): number |tiktok_app_id: string <br>campaign_id(in Context object): string<br>ad_id(in Context object): string<br>creative_id` (in Context object): string |


## 请求

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

**方法** POST

**Header**

```xtable
|字段|类型|描述|
|---|---|---|
|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 广告管理平台里为移动应用生成TikTok App ID。更多细节，请参考[TikTok应用ID](https://ads.tiktok.com/help/article?aid=10001060)。|
|batch {必填}|object[]|批量报告的一系列应用事件。长度必须大于 1 且小于 1000。|
#|type{必填} |string|应用事件类型。<br>目前仅支持 `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>部分。|

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/).|
##|idfv |string|iOS idfv|
##|gaid |string|谷歌广告ID|
##|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|产品类商品的类型。可以是对产品类商品的描述（例如：被购买）|
##|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/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)
← 获取应用信息更新应用 →

内容来源：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 每日平台更新简报 →