常用的 函数
基础函数
初始化 SDK：InitTonAI()
用于在使用 SDK 之前初始化，需要传入你的 appId
import { InitTonAI } from 'ton-ai-sdk'
InitTonAI({ appId: 'your_app_id' })
// 如果是在 staging 环境，请传入 debug 参数
InitTonAI({ appId: 'your_app_id', debug: true })设置用户 openId SetUserOpenId()
用于设置用户的 openId,非必选 SDK 会自动从 Telegram.WebApp 中获取用户的 user id 作为 openId，如果你需要自己设置 openId，请调用此函数 openId 是作为用户的唯一身份标志，请确保每个用户都有一个唯一的 openId 在 Telegram 中，请使用用户的 Telegram user id (Telegram.WebApp.initDataUnsafe.user.id)作为 openId
import { SetUserOpenId } from 'ton-ai-sdk'
SetUserOpenId('your_user_open_id')更新用户画像：UpdateUserProfile()
用于更新用户画像，需要传入用户的画像数据
import { UpdateUserProfile } from 'ton-ai-sdk'
UpdateUserProfile({
walletAddress: '0x128**5678', // 用户钱包地址
walletClassify: 'string', // 'ton' | 'evm'
telegramUserId: 'string', // Telegram 用户 ID
})获取当前用户的设备指纹：GetDeviceId()
先从 SDK 中导入对应函数
import { GetDeviceId } from 'ton-ai-sdk'在页面渲染完成之后调用，例如在 useEffect 中（如果项目有开启了 SSR，请确保函数是在客户端被调用）
useEffect(() => {
const deviceId = GetDeviceId()
console.log('deviceId = ', deviceId)
}, [])获取当前用户的 Telegram User Info ：GetTelegramUserInfo()
先从 SDK 中导入对应函数
import { GetTelegramUserInfo } from 'ton-ai-sdk'在页面渲染完成之后调用，例如在 useEffect 中（如果项目有开启了 SSR，请确保函数是在客户端被调用）
useEffect(() => {
const tgUser = GetTelegramUserInfo()
console.log('tgUser = ', tgUser)
}, [])上报自定义事件 SendCommonEvent()
你可以增加一些自定义的事件，例如用户登录、用户打开某个页面、用户完成某个任务等
import { SendCommonEvent } from 'ton-ai-sdk'
useEffect(() => {
const userOpenId = 'tg_user_id' // 用户唯一标识，在 Telegram 中为用户的 tg_user_id
const eventName = 'user_login' // 自定义事件的名称
SendCommonEvent(eventName, userOpenId)
}, [])广告相关函数
获取广告数据 GetMultiTonAd()
获取一个或多个广告数据
import { GetMultiTonAd } from 'ton-ai-sdk'
const blockId = 'your_block_id' // 你的广告位 ID
const limit = 5 // 获取广告的数量
GetMultiTonAd(blockId, limit)
.then((ads) => {
if (ads && ads.length > 0) {
// 广告加载成功，可以在适当的时机展示
} else {
// 没有可用的广告
}
})
.catch((error) => {
console.error('加载广告失败:', error)
})返回的 ads 对象的结构如下：
{
"ads": [
{
"adId": "string", // 广告 ID
"adBlockId": "string", // 广告位 ID
"adFormat": "string", //"image" | "video",
"campaignId": "string", // 广告活动 ID
"image": "string", // 广告图片
"icon": "string", // 广告商家图标
"popupImage": "string", // 广告弹窗图片
"brandName": "string", // 广告商家名称
"text": "string", // 广告文案
"buttonText": "string", // 按钮文案
"url": "string", // 广告跳转链接
"destination": {
// option: 广告跳转的具体配置
"actionType": "string",
"url": "string",
"destinationConfig": {
"url": "string",
"telegramLink": "string"
}
}
}
]
}弹出广告弹窗 TonAdPopupShow()
以全屏弹窗的形式展示一个广告
- 可以直接传入广告数据对象:
tonAd - 也可以传入广告位 ID ：
blockId
import { TonAdPopupShow } from 'ton-ai-sdk'
const blockId = 'your_block_id' // 你的广告位 ID
TonAdPopupShow({
blockId,
onAdClick: (ad) => {
// 广告被点击时触发
console.log('Ad clicked:', ad)
// 请在这里处理广告点击后的逻辑,例如发放奖励或者道具
// sendReward()
},
onAdError: (error) => {
// 广告加载失败时触发
console.error('Ad error:', error)
},
})上报广告点击事件 SendTonAdClickEvent()
用于上报广告点击事件
import { SendTonAdClickEvent } from 'ton-ai-sdk'
// 直接传入从 api 拿到的广告数据对象
sendTonAdClickEvent(ad:TonAdProps)TonAdProps 结构如下：
{
adId: string
adBlockId: string
adFormat: 'image' | 'video'
campaignId: string
image: string
icon: string
popupImage?: string
brandName?: string
text: string
buttonText?: string
url?: string
destination: {
actionType: string
url?: string
destinationConfig: DestinationConfigProps
}
}上报广告转化事件 SendTonAdConversion()
用于上报广告转化事件
- 当你发现用户来自你所投放的广告时（例如带有特定的 channel），可以调用此函数上报广告转化事件
import { SendTonAdConversion } from 'ton-ai-sdk'
SendTonAdConversion({
telegramUserId: 'string', // Telegram 用户 ID
})换量相关函数
获取换量广告数据 GetMultiTonExchangeAd()
获取一个或多个广告数据
import { GetMultiTonExchangeAd } from 'ton-ai-sdk'
const exchangeId = 'your_exchange_id' // 你的换量 ID
const limit = 5 // 获取广告的数量
GetMultiTonExchangeAd(exchangeId, limit)
.then((ads) => {
if (ads && ads.length > 0) {
// 广告加载成功，可以在适当的时机展示
} else {
// 没有可用的广告
}
})
.catch((error) => {
console.error('加载广告失败:', error)
})返回的 ads 对象的结构如下：
{
"ads": [
{
"inExchangeCampaignId": "string", // 目标广告 ID
"outExchangeCampaignId": "string", // 你当前的广告 ID
"adFormat": "string", //"image" | "video",
"campaignId": "string", // 广告活动 ID
"image": "string", // 广告图片
"icon": "string", // 广告商家图标
"popupImage": "string", // 广告弹窗图片
"brandName": "string", // 广告商家名称
"text": "string", // 广告文案
"buttonText": "string", // 按钮文案
"url": "string", // 广告跳转链接
"destination": {
// option: 广告跳转的具体配置
"actionType": "string",
"url": "string",
"destinationConfig": {
"url": "string",
"telegramLink": "string"
}
}
}
]
}弹出换量广告弹窗 TonExchangePopupShow()
以全屏弹窗的形式展示一个广告
- 可以直接传入广告数据对象:
exchangeAd - 也可以传入换量 ID ：
exchangeId
import { TonExchangeAdPopupShow } from 'ton-ai-sdk'
TonExchangeAdPopupShow({
exchangeId: 'your_exchange_id', // 你的换量 ID
onAdClick: (ad) => {
// 广告被点击时触发
console.log('Ad clicked:', ad)
// 请在这里处理广告点击后的逻辑,例如发放奖励或者道具
// sendReward()
},
onAdError: (error) => {
// 广告加载失败时触发
console.error('Ad error:', error)
},
})
// 或者
TonExchangeAdPopupShow({
exchangeAd: ad, // 或者直接传入换量广告数据对象
onAdClick: (ad) => {
// 广告被点击时触发
console.log('Ad clicked:', ad)
// 请在这里处理广告点击后的逻辑,例如发放奖励或者道具
// sendReward()
},
onAdError: (error) => {
// 广告加载失败时触发
console.error('Ad error:', error)
},
})换量广告点击处理 OnExchangeAdClick
用户点击换量广告，您需要调用 SDK OnExchangeAdClick 来处理点击事件即可，不再需要手动上报 click 事件
OnExchangeAdClick 将会处理：
- 广告 url 跳转
- click 事件上报
- 广告验证
- 任务完成
import { OnExchangeAdClick } from 'ton-ai-sdk'
// ad 是 ads 中的一个对象
OnExchangeAdClick(ad, onVerifySuccess=({success:boolean, ad:TonExchangeAdProps,message:string})=>{
if(success){
// 验证成功，可以设置任务为完成状态,并且发送任务奖励
// sendReward()
}else{
// 验证失败，可以提示用户重试
}
})上报换量广告点击事件 SendTonExchangeClickEvent()
提示
尽量使用 OnExchangeAdClick 来处理换量广告点击事件，不再需要手动上报 click 事件
当你在展示换量广告时，用户点击了广告，然后你自己处理了点击跳转逻辑，那么可以调用此函数上报广告点击事件。（不过还是推荐使用 OnExchangeAdClick，不需要自己处理跳转和上报 click 事件）
import { SendTonExchangeClickEvent } from 'ton-ai-sdk'
// 直接传入从 `GetTonExchangeAd` api 拿到的换量广告数据对象
SendTonExchangeClickEvent(ad: TonExchangeAdProps)上报换量广告转化事件 SendTonExchangeConversion()
用于上报换量广告转化事件
- 当你发现用户来自你所投放的换量广告时（例如带有特定的 channel），可以调用此函数上报广告转化事件
import { SendTonExchangeConversion } from 'ton-ai-sdk'
SendTonExchangeConversion({
telegramUserId: 'string', // Telegram 用户 ID
})