前言

除了默认 SDK 自动上报模式，Ton AI 还支持多种上报方式，您可以根据自己的需求选择合适的方式。

方案1：SDK 上报有效用户

前提

请参考 SDK 安装文档 完成 SDK 的初始化。

上报方法

如果您希望在用户完成指定动作时，手动上报有效用户，可以参考以下方法：

1. 在初始化 SDK 时，设置 disableDefaultConversion 为 true，禁用默认的上报机制。

import { TonAdInit } from 'ton-ai-sdk'

const result = TonAdInit({ appId: 'your-app-id', disableDefaultConversion: true})
console.log('TonAdInit', result)

2. 当用户完成指定动作时，上报 Conversion 事件

import { SendTonAdConversion } from 'ton-ai-sdk'

if (userHasConverted) {
  SendTonAdConversion()
}

提示

在 Telegram Mini APP 中，SDK 会自动获取当前登陆用户的 TelegramUserId，您也可以选择自己传入

import { SendTonAdConversion } from 'ton-ai-sdk'

const telegramUserId = '1234567890'
SendTonAdConversion(telegramUserId)

上报流程非常简单，只需要在用户完成指定动作时，调用 SendTonAdConversion 方法即可。

SDK 上报自定义事件

提示

Coming Soon 该功能即将开放

如果您还不确定要根据哪类事件类定义用户的转化，你可以选择上报自定义事件:

import { SendCommonEvent } from 'ton-ai-sdk'

// 上报自定义事件
SendCommonEvent('onboard')
SendCommonEvent('register')
SendCommonEvent('play')
SendCommonEvent('payment')
SendCommonEvent('withdraw')

然后在创建 Campaign 时选择使用哪个事件作为 Optimization 的依据。

方案2：使用 API 上报有效用户

如果您的 Mini APP 无法使用 SDK 上报有效用户，您可以使用 API 上报有效用户

请求方法

POST https://app.ton.ai/api/v2/openapi/ad/event/report/conversion

请求参数

参数名	位置	类型	必填	描述
x-api-key	header	string	是	如何获取 APP Key

请求体应为 JSON 格式，包含以下字段：

字段名	类型	必填	描述
eventType	string	是	事件类型，固定值为 "conversion"
eventData	object	是	事件数据，包含以下字段

eventData 对象包含以下字段：

字段名	类型	必填	描述
telegramUserId	string	是	用户的唯一 Telegram ID

完整请求示例

发起请求：

curl --request POST \
     --url https://staging.ton.ai/api/v2/openapi/ad/event/report/conversion \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR_API_KEY_HERE' \
     --data '
{
  "eventType": "conversion",
  "eventData": {
    "telegramUserId": "1728125519"
  }
}
'

成功响应会返回上传成功的状态，状态码为 200。响应格式如下：

{
  "status": "success"
}

方案3：提供 API 验证用户

您还可以通过提供 API 来让 Ton AI 验证用户是否有效。

Ton AI 会在用户点击广告后，查询您的 API 来验证用户是否真正进入广告主的产品中。

请求方法

GET

请求参数

参数名	类型	必须	描述
telegram_id	string	是	用户的 Telegram ID

返回值

返回值为字符串类型，表示验证结果：

• "true"：验证成功
• "false"：验证失败

成功验证示例

curl --location 'https://app.pea.ai/api/v1/common/verify/example/success' \
--header 'Content-Type: application/json' \
--data '{"telegram_id": "123456789"}'

返回结果：

"true"

验证失败示例

curl --location 'https://app.pea.ai/api/v1/common/verify/example/fail' \
--header 'Content-Type: application/json' \
--data '{"telegram_id": "987654321"}'

返回结果：

"false"