SDK Ad Integration

Prerequisites

Native Ads

We recommend displaying native ads in your app, for example by wrapping ads into tasks. This minimizes disruption to the user experience.

1. Fetch Ads

First, you need to load ads. The frontend calls the SDK function GetMultiTonAd to get ads.

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

const blockId = 'your_block_id'
const limit = 5
GetMultiTonAd(blockId, limit)
  .then((ads) => {
    if (ads && ads.length > 0) {
      // Ads loaded successfully, can be displayed at the right time
    } else {
      // No ads available
    }
  })
  .catch((error) => {
    console.error('Failed to load ads:', error)
  })

Tips

We recommend fetching multiple ads at once to offer users choices and increase the click-through rate.

During testing, set debug: true when initializing the SDK if no ads are retrieved.

The structure of the ads object is as follows:

{
  "ads": [
    {
      "adId": "string", // Ad ID
      "adBlockId": "string", // Ad Block ID
      "adFormat": "string", //"image" | "video",
      "icon": "string", // Advertiser's Icon
      "text": "string", // Ad Text
      "buttonText": "string", // Button Text
      "url": "string", // Ad Redirect URL
      "destination": {
        "actionType": "string",
        "url": "string"
      }
    }
  ]
}

2. Wrap Ads

You can then take parameters like

  • icon
  • text

from the Ad to render tasks in the Earn page, like this:

3. Display Ads

After a user clicks a task, you need to call the SDK to display the ad and pass in the ad object clicked by the user.

TonAdPopupShow({
  tonAd: ad, // Ad object clicked by the user
  countdown: 15,  // Optional, default is 10 seconds, minimum 10 seconds, maximum 30 seconds
  autoClose: true, // Default is true, meaning the ad will close automatically after the countdown
  onAdComplete: (ad) => {
    // The user has completed watching the ad, you can grant a reward here
    // sendReward(ad)
  },
  onAdClick: (ad) => {
    // The user has clicked the ad, you can grant a reward here
    // sendReward(ad)
  },
  onAdError: (error) => {
    // The user encountered an error while watching the ad
    console.error(error)
  },
  onAdClose: (ad) => {
    // The user manually closed the ad
  }
})

Then, depending on your product design, choose to send rewards at the appropriate time.

  • onAdComplete: Corresponds to CPM mode, meaning the user gets a reward after watching the ad.
  • onAdClick: Corresponds to CPC mode, providing a strong incentive for users to get a reward after clicking the ad.

Tips

If you want the logic for sending rewards to not be executed on the frontend, you can refer to the reward-webhook section in getBlockId.

The structure of the returned ad object in various events is as follows:

{
      "adId": "string", // Ad ID
      "adBlockId": "string", // Ad Block ID
      "adFormat": "string", //"image" | "video",
      "icon": "string", // Advertiser's Icon
      "text": "string", // Ad Text
      "buttonText": "string", // Button Text
      "url": "string", // Ad Redirect URL
}

Ad Display Effects

Ad Effects
Ad Effects

Click here for the full example code