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

报告线下事件和参数

本文列出了当您使用/v1.3/offline/track/ 或/v1.3/offline/batch/ 报告线下事件时支持的线下事件和参数。

支持的线下事件

线下事件是指顾客在线下达成某一业务目标的行为。标准事件是指 TikTok For Business 预先定义的支持的线下行为。下表汇总了支持的线下事件。事件名称区分大小写，因此请务必使用事件列中显示的确切名称。

|事件{30%} |示例{70%} |
|---|---|---|---|
|Purchase|支付完成，包括门店购买及控制台购买。|
|Contact|咨询，包括电话服务中心事件以及沟通事件。|
|Subscribe|订阅，包括门店订阅及控制台订阅。|
|Lead|<p><span style="color:darkred"><b>注意</b></span>：如果广告主不能通过网页事件API传递TikTok线索ID，他们应该采取线下路径。|
| AddPaymentInfo | 在收银台添加支付信息。 |
| AddToCart | 将商品加入购物车。 |
|ApplicationApproval | 开始试用产品或服务。|
| AddToWishlist | 将商品加入心愿单。 |
| CompleteRegistration | 完成注册，例如注册账户。 |
| Download | 在您的网站进行下载。 |
| InitiateCheckout | 开始结账。 |
| Search | 搜索。 |
| ViewContent | 查看页面内容。 |
|StartTrial|开始试用产品或服务。|
|SubmitApplication|提交申请。|
| CustomizeProduct | 定制商品。   |
| FindLocation | 试图寻找您的位置。   |
| Schedule | 预约与您的企业交谈或实地来访。   |

报告单个线下事件

您可以使用接口/v1.3/offline/track/，报告单个线下事件。

请求

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

方法：POST

Header

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

参数

|字段{30%}|类型{10%}|描述{20%}|示例{20%}|
| --- | --- | --- |
|event {必填}|string |事件类型。参考上方“支持的线下事件”小节获取支持的事件类型。|Purchase
|event_set_id {必填} |string |事件组ID。|7057103914977558530
|event_id|string|每个事件的唯一值。该ID可以用来匹配合作伙伴和TikTok之间的数据。我们建议该值为一个32个字符的字符串，包括数字（0-9）、大写字母（A-Z）和小写字母（a-z）。|1616318632825_357
|context{必填} |object  | 事件发生的背景环境。详细信息请参考下方的“User context对象参数”小节。|参考下方的“User context对象参数”小节。
|properties {必填}|object  |与事件关联的属性，例如收入。详细信息请参考下方的“Properties对象参数”小节。|参考下方的“Properties对象参数”小节。|
|timestamp{必填} |datetime  | 事件发生的时间戳信息。格式为[ISO_8601](https://en.wikipedia.org/wiki/ISO_8601)。|2019-06-12T19:11:01.152Z

示例

注意
您需要将示例中的虚拟数据替换为自己的数据。

(code cURL HTTP)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/offline/track/' \
--header 'Access-Token:  {{Access-Token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "event_set_id":" {{event_set_id}}", 
  "event": "Purchase",
  "event_id":" {{event_id}}", 
  "timestamp": "2020-09-17T19:49:27Z",     
  "context": {
    "user": {
      "phone_numbers": ["2f9d2b4df907e5c9a7b3434351b55700167b998a83dc479b825096486ffcf4ea",
      "1e7c3b4ff108e5c9a7b3434351b55700167b998a83dc479b825096486cvvf6gt"],
      "emails": ["dd6ff77f54e2106661089bae4d40cdb600979bf7edc9eb65c0942ba55c7c2d7f"]
    }
  },
  "properties": {
    "order_id": "abc_xyz", 
    "shop_id": "123abc",
    "contents": [
      {
        "price": 8,
        "quantity": 2,
        "content_type": "product",
        "content_id": "1077218",
        "content_name": "socks",
        "content_category": "Men's cloth"
      },
      {
        "price": 30,
        "quantity": 1,
        "content_type": "product",
        "content_id": "1197218",
        "content_name": "Nike Air Jordan 1",
        "content_category": "Men's shoes"
      }
    ],
    "event_channel": "in_store",
    "currency": "USD",
    "value": 46.00
  }
}
'
(/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",
    "data":{}
}
(/code);

批量报告线下事件

您可以使用接口/v1.3/offline/batch/，批量报告线下事件，减少API的访问量。我们建议您每次发送批量事件时，发送的事件总数不超过100个，且总事件的大小不超过 10 MB。

请求

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

方法 POST

Header

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

参数

|字段{30%}|类型{10%}|描述{40%}|示例{20%}|
|---|---|---|---|
|event_set_id  |string |事件组ID。|7057103914977558530
|batch|object[]|线下事件列表。| 
#|event {必填}|string |事件类型。参考上方“支持的线下事件”小节获取支持的事件类型。|Purchase
#|event_id|string|每个事件的唯一值。该ID可以用来匹配合作伙伴和TikTok之间的数据。我们建议该值为一个32个字符的字符串，包括数字（0-9）、大写字母（A-Z）和小写字母（a-z）。|1616318632825_357
#|context{必填} |object  | 事件发生的背景环境。详细信息请参考下方的“User context对象参数”小节。|参考下方的“User context对象参数”小节。
#|properties {必填}|object  |与事件关联的属性，例如收入。详细信息请参考下方的“Properties对象参数”小节。|参考下方的“Properties对象参数”小节。|
#|timestamp{必填} |datetime  | 事件发生的时间戳信息。格式为[ISO_8601](https://en.wikipedia.org/wiki/ISO_8601)。|2019-06-12T19:11:01.152Z

示例

注意
您需要将示例中的虚拟数据替换为自己的数据。

(code cURL HTTP)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/offline/batch/' \
--header 'Access-Token: {{Access-Token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "event_set_id": "{{event_set_id}}",
    "batch": [{
            "event": "Purchase",
            "event_id": "{{event_id}}",
            "timestamp": "2020-09-17T19:49:27Z",
            "context": {
                "user": {
                    "phone_numbers": ["2f9d2b4df907e5c9a7b3434351b55700167b998a83dc479b825096486ffcf4ea",
                        "1e7c3b4ff108e5c9a7b3434351b55700167b998a83dc479b825096486cvvf6gt"
                    ],
                    "emails": ["dd6ff77f54e2106661089bae4d40cdb600979bf7edc9eb65c0942ba55c7c2d7f"]
                }
            },
            "properties": {
                "order_id": "abc_xyz",
                "shop_id": "123abc",
                "contents": [{
                        "price": 8,
                        "quantity": 2,
                        "content_type": "product",
                        "content_id": "1077218",
                        "content_name": "socks",
                        "content_category": "Men's cloth"
                    },
                    {
                        "price": 30,
                        "quantity": 1,
                        "content_type": "product",
                        "content_id": "1197218",
                        "content_name": "Nike Air Jordan 1",
                        "content_category": "Men's shoes"
                    }
                ],
                "event_channel": "in_store",
                "currency": "USD",
                "value": 46.00
            }
        },
        {
            "event": "Purchase",
            "event_id": "{{event_id}}",
            "timestamp": "2020-09-18T20:50:27Z",
            "context": {
                "user": {
                    "phone_numbers": ["2f9d2b4df907e5c9a7b3434351b55700167b998a83dc479b825096486ffcf4ea",
                        "1e7c3b4ff108e5c9a7b3434351b55700167b998a83dc479b825096486cvvf6gt"
                    ],
                    "emails": ["dd6ff77f54e2106661089bae4d40cdb600979bf7edc9eb65c0942ba55c7c2d7f"]
                }
            },
            "properties": {
                "order_id": "abc_xyz_2",
                "shop_id": "123abc",
                "contents": [{
                        "price": 20,
                        "quantity": 1,
                        "content_type": "product",
                        "content_id": "1077220",
                        "content_name": "Jacket",
                        "content_category": "Men's cloth"
                    },
                    {
                        "price": 100,
                        "quantity": 1,
                        "content_type": "product",
                        "content_id": "1197221",
                        "content_name": "Jeans",
                        "content_category": "Men's cloth"
                    }
                ],
                "event_channel": "in_store",
                "currency": "USD",
                "value": 120.00
            }
        }
    ]
}
'
(/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",
    "data":{}
}

(/code);

User context对象参数

下表介绍了context对象中支持的字段。phone_numbers和emails字段必须传其中一个，并至少传入一个值。

|字段{20%}|类型{10%}|描述{25%}|格式{30%}|示例{15%}|
|---|---|---|---|---|
|user{必填} |object|用户的个人数据。 | | |
#|phone_numbers|string[]|用户的电话号码。<br>必须在客户端用SHA-256加密。您必须传入本字段或`emails`。 |在加密之前，进行以下格式设置：<ul><li>将电话号码转为E.164格式，即+［国家/地区代码]［电话号码]。例如，某个美国电话号码的E.164格式：+12133734253</li><li>推荐使用[https://github.com/catamphetamine/libphonenumber-js](https://github.com/catamphetamine/libphonenumber-js)进行E.164解析。</li><li>仅接受 SHA-256。参考文档： [GitHub - emn178/js-sha256: A simple SHA-256 / SHA-224 hash function for JavaScript supports UTF-8 encoding.](https://github.com/emn178/js-sha256)|["sha256phone1","sha256phone2"]|
##|emails|string[]|用户的邮箱地址。 <br>必须在客户端用SHA-256加密。您必须传入本字段或`phone_numbers`。 |在加密之前，进行以下格式设置：<ul><li>需要在散列处理前统一使用小写字母。</li><li>在散列处理前不要对邮箱进行其他预处理。</li><li>仅接受 SHA-256。参考文档：[GitHub - emn178/js-sha256: A simple SHA-256 / SHA-224 hash function for JavaScript supports UTF-8 encoding.](https://github.com/emn178/js-sha256)|["sha256email1", "sha256email2"]

Properties对象参数

下表介绍了properties对象中支持的字段。

|字段{20%}|类型{10%}|描述{35%}|示例{35%}|
|---|---|---|---|
|order_id|string|订单ID。|abc_xyz|
|shop_id|string| 商店ID。| 
|contents|object[]|线下事件中的相关商品。| 
#|content_name|string|商品名称。|socks|
#|content_type|string|商品类型。|product|
#|content_category|string|商品类别。|Men's cloth|
#|content_id|string|商品ID。|230222800|
#|quantity|number|商品数量。|4|
#|price|number|商品价格。|125.05|
#|brand|string |商品的品牌名称。||
|currency{+条件必填}|string|币种，采取ISO 4217 代码。收入报表必填。示例："USD"。<br><strong>目前支持的币种清单：</strong> 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。|USD|
|value{+条件必填}|number|所有商品的带来的收入。收入报表必填。|125.05|
|event_channel|string|事件发生的渠道。枚举值：<ul><li>email<li>website<li>phone_call<li> in_store<li>crm<li>other|in_store|
← 快速入门常见问题 →

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