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:

1. Ad URL redirection
2. Click event reporting
3. Ad verification
4. 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
})