Common Functions
Basic Functions
Initialize SDK: InitTonAI()
Use this function to set up the SDK before use. You'll need to pass in your appId
.
import { InitTonAI } from 'ton-ai-sdk'
InitTonAI({ appId: 'your_app_id' })
// If in a staging environment, pass in the debug parameter
InitTonAI({ appId: 'your_app_id', debug: true })
Set User OpenId SetUserOpenId()
This sets a user's openId; it's optional. By default, the SDK automatically retrieves the user's ID from Telegram.WebApp
as the openId. If you wish to set it manually, use this function. The openId uniquely identifies a user—ensure each user has a distinct openId. In Telegram, use the user's Telegram user ID (Telegram.WebApp.initDataUnsafe.user.id
) as the openId.
import { SetUserOpenId } from 'ton-ai-sdk'
SetUserOpenId('your_user_open_id')
Update User Profile: UpdateUserProfile()
Use this to update the user profile, requiring their profile data.
import { UpdateUserProfile } from 'ton-ai-sdk'
UpdateUserProfile({
walletAddress: '0x128**5678', // User's wallet address
walletClassify: 'string', // 'ton' | 'evm'
telegramUserId: 'string', // Telegram user ID
})
Get Current User's Device Fingerprint: GetDeviceId()
First, import the function from the SDK
import { GetDeviceId } from 'ton-ai-sdk'
Call it once the page is rendered, e.g., within useEffect
(ensure it's called client-side if SSR is enabled).
useEffect(() => {
const deviceId = GetDeviceId()
console.log('deviceId = ', deviceId)
}, [])
Get Current User's Telegram User Info: GetTelegramUserInfo()
First, import the function from the SDK
import { GetTelegramUserInfo } from 'ton-ai-sdk'
Call it once the page is rendered, e.g., within useEffect
(ensure it's called client-side if SSR is enabled).
useEffect(() => {
const tgUser = GetTelegramUserInfo()
console.log('tgUser = ', tgUser)
}, [])
Report Custom Events: SendCommonEvent()
Create custom events like user login, opening a page, or completing a task.
import { SendCommonEvent } from 'ton-ai-sdk'
useEffect(() => {
const userOpenId = 'tg_user_id' // Unique user identifier, in Telegram it's the tg_user_id
const eventName = 'user_login' // Name of the custom event
SendCommonEvent(eventName, userOpenId)
}, [])
Advertisement Functions
Get Advertisement Data: GetMultiTonAd()
Retrieve one or more advertisement data.
import { GetMultiTonAd } from 'ton-ai-sdk'
const blockId = 'your_block_id' // Your ad slot ID
const limit = 5 // Number of ads to retrieve
GetMultiTonAd(blockId, limit)
.then((ads) => {
if (ads && ads.length > 0) {
// Ads loaded successfully, display them at the desired time
} else {
// No ads available
}
})
.catch((error) => {
console.error('Failed to load ads:', error)
})
The structure of the returned ads object is as follows:
{
"ads": [
{
"adId": "string", // Ad ID
"adBlockId": "string", // Ad slot ID
"adFormat": "string", //"image" | "video",
"campaignId": "string", // Campaign ID
"image": "string", // Ad image
"icon": "string", // Advertiser icon
"popupImage": "string", // Popup ad image
"brandName": "string", // Advertiser name
"text": "string", // Ad text
"buttonText": "string", // Button text
"url": "string", // Ad URL
"destination": {
// Option: specific ad destination configuration
"actionType": "string",
"url": "string",
"destinationConfig": {
"url": "string",
"telegramLink": "string"
}
}
}
]
}
Display Ad Popup: TonAdPopupShow()
Show an ad as a full-screen popup.
- You can pass the ad data object:
tonAd
- Or you can pass the ad slot ID:
blockId
import { TonAdPopupShow } from 'ton-ai-sdk'
const blockId = 'your_block_id' // Your ad slot ID
TonAdPopupShow({
blockId,
onAdClick: (ad) => {
// Triggered when the ad is clicked
console.log('Ad clicked:', ad)
// Handle logic after ad click, e.g., give rewards or items
// sendReward()
},
onAdError: (error) => {
// Triggered when ad fails to load
console.error('Ad error:', error)
},
})
Report Ad Click Event: SendTonAdClickEvent()
Use this to report an ad click event.
import { SendTonAdClickEvent } from 'ton-ai-sdk'
// Directly pass the ad data object obtained from the API
sendTonAdClickEvent(ad:TonAdProps)
Structure of 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
}
}
Report Ad Conversion Event: SendTonAdConversion()
Use this to report an ad conversion event.
- If you notice the user comes from an ad you promoted (e.g., with a specific channel), call this function to report the ad conversion.
import { SendTonAdConversion } from 'ton-ai-sdk'
SendTonAdConversion({
telegramUserId: 'string', // Telegram user ID
})
Exchange-related Functions
Get Exchange Ad Data: GetMultiTonExchangeAd()
Retrieve one or more exchange ad data.
import { GetMultiTonExchangeAd } from 'ton-ai-sdk'
const exchangeId = 'your_exchange_id' // Your exchange ID
const limit = 5 // Number of ads to retrieve
GetMultiTonExchangeAd(exchangeId, limit)
.then((ads) => {
if (ads && ads.length > 0) {
// Ads loaded successfully, display them at the desired time
} else {
// No ads available
}
})
.catch((error) => {
console.error('Failed to load ads:', error)
})
The structure of the returned ads object is as follows:
{
"ads": [
{
"inExchangeCampaignId": "string", // Target ad ID
"outExchangeCampaignId": "string", // Your current ad ID
"adFormat": "string", //"image" | "video",
"campaignId": "string", // Campaign ID
"image": "string", // Ad image
"icon": "string", // Advertiser icon
"popupImage": "string", // Popup ad image
"brandName": "string", // Advertiser name
"text": "string", // Ad text
"buttonText": "string", // Button text
"url": "string", // Ad URL
"destination": {
// Option: specific ad destination configuration
"actionType": "string",
"url": "string",
"destinationConfig": {
"url": "string",
"telegramLink": "string"
}
}
}
]
}
Display Exchange Ad Popup TonExchangePopupShow()
Show an ad as a full-screen popup
- You can pass the ad data object:
exchangeAd
- Or you can pass the exchange ID:
exchangeId
import { TonExchangeAdPopupShow } from 'ton-ai-sdk'
TonExchangeAdPopupShow({
exchangeId: 'your_exchange_id', // Your exchange ID
onAdClick: (ad) => {
// Triggered when the ad is clicked
console.log('Ad clicked:', ad)
// Handle logic after ad click, e.g., give rewards or items
// sendReward()
},
onAdError: (error) => {
// Triggered when ad fails to load
console.error('Ad error:', error)
},
})
// Or
TonExchangeAdPopupShow({
exchangeAd: ad, // Or directly pass exchange ad data object
onAdClick: (ad) => {
// Triggered when the ad is clicked
console.log('Ad clicked:', ad)
// Handle logic after ad click, e.g., give rewards or items
// sendReward()
},
onAdError: (error) => {
// Triggered when ad fails to load
console.error('Ad error:', error)
},
})
Handle Exchange Ad Click OnExchangeAdClick
When users click on exchange ads, you'll need to use the SDK's OnExchangeAdClick
to process the click event. You no longer need to manually report the click event.
OnExchangeAdClick will handle:
- Ad URL redirection
- Click event reporting
- Ad verification
- Task completion
import { OnExchangeAdClick } from 'ton-ai-sdk'
// ad is an object from the ads array
OnExchangeAdClick(ad, onVerifySuccess=({success:boolean, ad:TonExchangeAdProps,message:string})=>{
if(success){
// Verification successful, mark task as completed and send reward
// sendReward()
}else{
// Verification failed, prompt the user to retry
}
})
Report Exchange Ad Click Event SendTonExchangeClickEvent()
Tips
Prefer using OnExchangeAdClick
to handle exchange ad click events. You no longer need to manually report the click event.
If you're displaying exchange ads and users click on them while you handle the click redirection logic yourself, you can call this function to report the ad click event. (However, it's recommended to use OnExchangeAdClick
to avoid handling redirection and click event reporting manually.)
import { SendTonExchangeClickEvent } from 'ton-ai-sdk'
// Directly pass the exchange ad data object obtained from the `GetTonExchangeAd` API
SendTonExchangeClickEvent(ad: TonExchangeAdProps)
Report Exchange Ad Conversion Event: SendTonExchangeConversion()
Use this to report an exchange ad conversion event.
- If you notice users coming from an exchange ad you promoted (e.g., with a specific channel), call this function to report the ad conversion.
import { SendTonExchangeConversion } from 'ton-ai-sdk'
SendTonExchangeConversion({
telegramUserId: 'string', // Telegram user ID
})