创建自定义转化

您可以使用本接口为 Pixel 或应用创建自定义转化。

注意
- 最多可以在一个广告账户中创建 1,000 个自定义转化。 - 对于单个 Pixel 或应用，最多可创建 100 个自定义转化。

请求

地址 https://business-api.tiktok.com/open_api/v1.3/custom_conversion/create/

方法 POST

Header

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](1738373164380162.html)接口获取。|
|Content-Type {必填}|string|请求信息类型。<br>允许格式: `application/json`。  |

参数

|字段{30%}|类型{15%}|描述{55%}|
|--- |--- |--- |
|advertiser_id {必填}|string|广告主 ID。|
|name {必填}|string|自定义转化的名称。<br>名称必须以字母开头，可以包含字母、数字、空格、下划线或横线。<br><br>长度限制: 50 个字符，不能包含表情符号。<br><br><p><span style="color:darkred"><b>注意</b></span>:<ul><li>不要指定标准事件的名称。</li><li>不允许在广告账户内重复使用自定义转化名称。</li></ul> |
|description|string|自定义转化的描述。<br><br>长度限制: 500 个字符，不能包含表情符号。|
|event_source_type {必填}|string|事件源类型。<br><br>枚举值:<ul><li>`PIXEL`: Pixel。</li><li>`APP`: 应用。</li></ul>|
|event_source_id {必填}|string|事件源 ID。<br><br><ul><li>当 `event_source_type` 为 `PIXEL` 时，指定一个 Pixel ID。<ul><li>要获取广告账户中的 Pixel ID，可使用[/pixel/list/](1740858697598978.html)并检查返回的`pixel_id`。</li></ul></li><li>当 `event_source_type` 为 `APP` 时，指定自归因网络应用的应用平台 ID。<ul><li>此应用只能与 TikTok 应用事件 SDK 一起使用。SDK 能建立从您的应用到 TikTok 的直接第一方连接，可减少信号丢失并提供更准确的测量。了解[如何安装 SDK](1739584951798785.html)。</li><li>要获取广告账户中自归因应用的应用平台 ID，可使用[/app/list/](1740859313270786.html)。确认应用的 `self_attribution_enabled` 返回值为 `true` 并检查返回的 `app_platform_id`。</li></ul></li></ul>|
|optimization_event {+条件必填}|string|<ul><li>在以下任一场景下，本字段必填：</li><ul><li>`event_source_type` 为 `PIXEL` 时。</li><li>`event_source_type` 为 `APP` 且您使用标准事件创建自定义转化时。</li><li>`event_source_type` 为 `APP` 且您使用自定义事件创建自定义转化，且应用已启用将自定义事件映射为标准事件的白名单时。</li></ul><li>满足以下所有条件时不支持本字段：</li><ul><li>`event_source_type` 为`APP`。</li><li>您使用自定义事件创建自定义转化。</li><li>应用未启用将自定义事件映射为标准事件的白名单。</li></ul></ul><br>要与自定义转化关联的标准事件。<br><br>枚举值参阅<a href="#item-link-optimization_event 的可选值">`optimization_event` 的可选值</a>。<br><br><p><span style="color:darkred"><b>注意</b></span>：在使用应用事件源和自定义事件创建自定义转化时将自定义事件映射为标准事件目前为白名单功能。如需使用此功能，请联系您的 TikTok 销售代表。</p>|
|custom_event_type|string|仅当已为应用或 Pixel (`event_source_id`) 配置自定义事件时生效。<br><br>要与自定义转化关联的自定义事件。<br>当为自定义转化指定自定义事件时，需要同时通过 `optimization_event` 指定要映射到的标准事件。<br>自定义事件是 TikTok 合作伙伴可以在预定义的标准事件列表之外自行定义的操作。要了解有关自定义事件的更多信息，参阅[关于 TikTok 广告管理平台中的自定义事件](https://ads.tiktok.com/help/article/custom-events)。<br><br>要获取为 Pixel 配置的自定义事件，可使用[/pixel/list/](1740858697598978.html)并检查返回的`custom_event_type`。<br><br><p><span style="color:darkred"><b>注意</b></span>：在使用应用事件源和自定义事件创建自定义转化时，需在创建自定义转化前，确保已接收到所指定的应用自定义事件（`custom_event_type`）的回传。否则，将出现报错。</p>|
|rules {必填}|object[]|自定义转化的转化规则详细信息。<br><br>只有满足这些条件的操作才会计为自定义转化。<br><br>数量范围: 1-10。|
#|parameter {必填}|string|参数。<br><br>枚举值:<ul><li>`BRAND`: `brand`。</li><li>`CONTENT_CATEGORY`: `content_category`。</li><li>`CONTENT_ID`: `content_id`。</li><li>`CONTENT_NAME`: `content_name`。</li><li>`CONTENT_TYPE`: `content_type`。</li><li>`CURRENCY`: `currency`。</li><li>`DESCRIPTION`: `description`。</li><li>`EVENT_ID`: `event_id`。</li><li>`NUM_ITEMS`: `num_items`。</li><li>`PRICE`: `price`。</li><li>`SEARCH_STRING`: `search_string`。</li><li>`STATUS`: `status`。</li><li>`URL`: `url`。</li><li>`VALUE`: `value`。</li></ul>|
#|operator {必填}|string|运算符。<br><br><ul><li>当 `parameter` 为 `BRAND`、`CONTENT_CATEGORY`、`CONTENT_ID`、`CONTENT_NAME`、`CONTENT_TYPE`、`DESCRIPTION`、`EVENT_ID`、`SEARCH_STRING`、`STATUS` 或 `URL` 时，枚举值为:<ul><li>`CONTAIN`: 包含。</li><li>`NOT_CONTAIN`: 不包含。</li><li>`START_WITH`: 开头是。</li><li>`EQUAL`: 等于。</li><li>`NOT_EQUAL`: 不等于。</li></ul></li><li>当 `parameter` 为 `NUM_ITEMS`、`PRICE` 或 `VALUE` 时，枚举值为:<ul><li>`EQUAL`: 等于。</li><li>`NOT_EQUAL`: 不等于。</li><li>`LT`: 小于。</li><li>`GT`: 大于。</li><li>`LTE`: 小于或等于。</li><li>`GTE`: 大于或等于。</li></ul></li><li>当 `parameter` 为 `CURRENCY` 时，枚举值为:<ul><li>`EQUAL`: 等于。</li><li>`NOT_EQUAL`: 不等于。</li></ul></li></ul>|
#|values {必填}|string[]|参数的值。<br><br><ul><li>当 `parameter` 为 `BRAND`、`CONTENT_CATEGORY`、`CONTENT_ID`、`CONTENT_NAME`、`CONTENT_TYPE`、`DESCRIPTION`、`EVENT_ID`、`SEARCH_STRING`、`STATUS`、`URL` 时，该字段将是一个字符串数组，每个字符串的最大长度为 100 个字符，最多 100 个条目。</li><li>当 `parameter` 为 `NUM_ITEMS` 时，该字段将是一个介于 0 和 1,000,000,000 之间的整数。</li><li>当 `parameter` 为 `PRICE`、`VALUE` 时，该字段将是一个保留两位小数的浮点数，取值范围为 0.00到 1,000,000,000.00。</li><li>当 `parameter` 为 `CURRENCY` 时，该字段将是一个字符串数组。要了解枚举值，请参阅<a href="#item-link-的可选值">的可选值</a>。|

optimization_event 的可选值

下表列出了不同事件源类型的optimization_event枚举值。

币种的可选值

下表列出了parameter为CURRENCY时values的枚举值。

| 币种值 {30%}| 币种名称{60%} |
|---|---|
| `AED` | 阿联酋迪拉姆 |
| `ALL` | 阿尔巴尼亚列克 |
| `AMD` | 亚美尼亚德拉姆 |
| `ARS` | 阿根廷比索 |
| `AUD` | 澳元 |
| `AZN` | 阿塞拜疆马纳特 |
| `BDT` | 孟加拉塔卡 |
| `BGN` | 保加利亚列弗 |
| `BHD` | 巴林第纳尔 |
| `BIF` | 布隆迪法郎 |
| `BOB` | 玻利维亚诺 |
| `BRL` | 巴西雷亚尔 |
| `BYN` | 白俄罗斯卢布 |
| `CAD` | 加拿大元 |
| `CHF` | 瑞士法郎 |
| `CLP` | 智利比索 |
| `CNY` | 人民币 |
| `COP` | 哥伦比亚比索 |
| `CRC` | 哥斯达黎加科朗 |
| `CZK` | 捷克克郎 |
| `DKK` | 丹麦克朗 |
| `DOP` | 多米尼加比索 |
| `DZD` | 阿尔及利亚第纳尔 |
| `EGP` | 埃及镑 |
| `EUR` | 欧元 |
| `GBP` | 英镑 |
| `GEL` | 格鲁吉亚拉里 |
| `GTQ` | 危地马拉格查尔 |
| `HKD` | 港元 |
| `HNL` | 洪都拉斯伦皮拉 |
| `HUF` | 匈牙利福林 |
| `IDR` | 印度尼西亚卢比 |
| `ILS` | 以色列新谢克尔 |
| `INR` | 印度卢比 |
| `ISK` | 冰岛克朗 |
| `JOD` | 约旦第纳尔 |
| `JPY` | 日元 |
| `KES` | 肯尼亚先令 |
| `KHR` | 柬埔寨瑞尔 |
| `KRW` | 韩元 |
| `KWD` | 科威特第纳尔 |
| `KZT` | 哈萨克斯坦坚戈 |
| `MAD` | 摩洛哥迪尔汗 |
| `MOP` | 澳门币 |
| `MXN` | 墨西哥比索 |
| `MYR` | 马来西亚林吉特 |
| `NGN` | 尼日利亚奈拉 |
| `NIO` | 尼加拉瓜科多巴 |
| `NOK` | 挪威克郎 |
| `NZD` | 新西兰元 |
| `OMR` | 阿曼里亚尔 |
| `PAB` | 巴拿马巴波亚 |
| `PEN` | 秘鲁新索尔 |
| `PHP` | 菲律宾比索 |
| `PKR` | 巴基斯坦卢比 |
| `PLN` | 波兰兹罗提 |
| `PYG` | 巴拉圭瓜拉尼 |
| `QAR` | 卡塔尔里亚尔 |
| `RON` | 罗马尼亚列伊 |
| `RSD` | 塞尔维亚第纳尔 |
| `RUB` | 俄罗斯卢布 |
| `SAR` | 沙特里亚尔 |
| `SEK` | 瑞典克朗 |
| `SGD` | 新加坡元 |
| `THB` | 泰铢 |
| `TND` | 突尼斯第纳尔 |
| `TRY` | 土耳其里拉 |
| `TWD` | 新台币 |
| `UAH` | 乌克兰格里夫纳 |
| `USD` | 美元 |
| `UZS` | 乌兹别克斯坦苏姆 |
| `VES` | 委内瑞拉玻利瓦尔 |
| `VND` | 越南盾 |
| `ZAR` | 南非兰特 |

示例

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/custom_conversion/create/' \
--header 'Access-token: {{Access-token}}' \
--header 'Content-Type: application/json' \
--data '{
    "advertiser_id": "{{advertiser_id}}",
    "name": "{{name}}",
    "description": "{{description}}",
    "event_source_type": "PIXEL",
    "event_source_id": "{{event_source_id}}",
    "optimization_event": "BUTTON",
    "rules": [
        {
            "operator": "EQUAL",
            "parameter": "CURRENCY",
            "values": [
                "AED",
                "AMD",
                "ARS",
                "AZN",
                "BDT"
            ]
        },
        {
            "operator": "NOT_CONTAIN",
            "parameter": "SEARCH_STRING",
            "values": [
                "{{search_string}}",
                "{{search_string}}"
            ]
        }
    ]
}'
(/code)

返回

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|code |number|返回码。完整返回码列表及描述参见[附录-返回码](1737172488964097.html)。 |
|message|string|返回信息。更多信息参见[附录-返回码](1737172488964097.html)。|
|request_id |string|请求的日志 ID，唯一标识一个请求。  |
|data |object|返回数据。|
#|custom_conversion_id|string|自定义转化的 ID。|

示例

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