Before starting the integration, make sure you have:
Added your Telegram Mini App (TMA) to TeleAds.
Created at least one active rewarded ad unit.
To connect your Mini App to the TeleAds advertising platform, insert the following script into the <head> of your app:
<script src="https://assets.teleads.pro/sdk/index.umd.js"></script>Initialize the TeleAds SDK using your SDK token:
TeleAdsTMA.init('YOUR_SDK_TOKEN');Optionally, add an onInitiated event handler to fire once the SDK is fully initialized.
When you’re debugging or testing, switch on debug mode—it logs every step of the init and ad-display flow.
TeleAdsTMA.init({
token: 'YOUR_SDK_TOKEN',
debug: true,
onInitiated: () => {
console.log('TeleAds SDK initiated!');
},
onError: (error: Error) => {
console.log('TeleAds SDK error:', error); },
});The SDK_TOKEN is generated immediately after connecting your platform in TeleAds.
To handle errors at any stage of the SDK workflow, add an onError event handler.
You can find more information on the platform configuration here.
To show an ad, call the showAd method and pass the adUnitId:
TeleAdsTMA.showAd({
adUnitId: 'AD_UNIT_ID'
});The adUnitId can be found in the platform dashboard under your list of created ad units.
Each connected platform can have up to 15 ad units.
You can optionally provide event handlers such as onAdLoaded, onTimeUpdated, and onClick:
TeleAdsTMA.showAd({
adUnitId: 'AD_UNIT_ID',
onAdLoaded: () => {
console.log('Ad loaded');
},
onTimeUpdated: ({ percent, currentTime }) => {
console.log(`Current ad display time: ${currentTime.toFixed()}s`);
},
onClick: () => {
console.log('User clicked the ad link');
},
});Handle the ad completion or failure using the promise returned by showAd:
.then(() => {
console.log('Ad completed successfully. Reward the user!');
})
.catch((error) => {
console.error('Failed to display ad', error);
});If the ad finishes successfully, we’ll send a GET request to the Reward URL you set for that ad unit — with [userId] and [publicationId] included as parameters.
A full code example is shown below:
TeleAdsTMA.showAd({
adUnitId: 'AD_UNIT_ID',
onAdLoaded: () => {
console.log('Ad loaded');
},
onTimeUpdated: ({ percent, currentTime }) => {
console.log(`Current ad display time: ${currentTime.toFixed()}s `);
},
onClick: () => {
console.log('User clicked the ad link');
},
})
.then(() => {
console.log('Ad completed successfully. Reward the user!');
})
.catch((error) => {
console.error('Failed to display ad', error);
}); To cancel the ad display, call the abort method.
TeleAdsTMA.abort();TeleAdsTMA.init(options: InitOptions): voidInitializes the TeleAds SDK. Must be called before using any ad functions.
options (InitOptions) — Object specifying token, debug mode, onInitiated and onError event handlers.
InitOptions
Configuration options for the init method.
Properties:
token (string): Your unique SDK token.
debug (boolean, optional): Enables debug mode to show logs and simplify integration.
onInitiated (function, optional): Callback invoked when the SDK is fully initialized.
onError (function, optional): Callback invoked when an error occurs while running the SDK. Receives an Error object as an argument.
TeleAdsTMA.showAd(options: ShowAdOptions): Promise<void>Displays an ad for the specified ad unit.
options (ShowAdOptions) — Object specifying the ad unit, onAdLoaded, onTimeUpdated and onClick event handlers.
ShowAdOptions
Configuration options for the showAd method.
Properties:
adUnitId (string): The ad unit ID in which to display the ad.
onAdLoaded (function, optional): Callback invoked when the video or static banner ad starts showing.
onTimeUpdated (function, optional): Callback invoked whenever the ad’s playback time updates.
onClick (function, optional): Callback invoked when the user clicks the ad.
TeleAdsTMA.abort(): void