Telegram Mini Apps Widget Integration Guide
Learn how to integrate ad widgets into your Telegram Mini Apps effectively.
Basic Integration
Integration in automatic mode:
html
<script type="text/javascript" src="https://cdn.tgads.space/assets/js/tg-ads-co-widget.min.js"></script>
<script type="text/javascript">
document.addEventListener('DOMContentLoaded', () => {
const adexiumAds = new AdexiumWidget({
wid: 'YOUR_WIDGET_ID',
adFormat: 'push-like', //adFormat values available: push-like/interstitial
firstAdImpressionIntervalInSeconds: 5, // by default ad will appear in 20 seconds after opening mini apps
adImpressionIntervalInSeconds: 100, // by default ad period interval is 200 seconds
debug: true, // you can pass this parameter to debug and get TEST ad every time you make request. Do not use on production ENV :)
isFullScreen: false // you can force enable full screen ads mode - just pass true
});
adexiumAds.autoMode(); // if you want to show AD in auto mode if not - do not call this method
});
</script>
Advanced Integration
If you would like to show ad manually there are some methods and events available to use:
Simple example of advanced integration (on button click):
js
document.addEventListener('DOMContentLoaded', () => {
// widget initialization
const adexiumAds = new AdexiumWidget({
wid: 'YOUR_WIDGET_ID',
adFormat: 'interstitial',
debug: true // remove this on production, use for test only
});
const button = document.getElementById('button');
// bind click event on button
button.onclick = () => {
// request ad
adexiumAds.requestAd('interstitial');
};
// subscribe on ad received event
adexiumAds.on('adReceived', (ad) => {
adexiumAds.displayAd(ad); // displaying ad
});
adexiumAds.on('noAdFound', () => {
// do something if ad is not found for user
});
});
Ad found and received:
javascript
const adReceivedListener = (ad) => {
adexiumAds.displayAd(ad); // display ad using our styles
//taskId = ad.id
};
// subscribe
adexiumAds.on('adReceived', adReceivedListener);
// unsubscribe
adexiumAds.off('adReceived', adReceivedListener);
Response example ad:
json
[{
"creativeUrl": "https://cdn.tgads.space/creatives/images/cf5e1ddb279099500910042f4c897ea2.webp",
"notificationUrl": "https://postback.tgads.live/impression?imp_id=64c286d8-04a2-4f4b-ac80-e455d8cbe020",
"clickUrl": "https://postback.tgads.live/click?click_id=64c286d8-04a2-4f4b-ac80-e455d8cbe020",
"buttonText": "Go!",
"title": "Ready for action, User? Play now!",
"adFormat": "push-like",
"description": "Blast Cannon: Aim, fire, win\u2014just for you! "
}]
## Events available
Ad not found:
javascript
const noAdFoundListener = () => {
console.log('no ad found');
};
// subscribe
adexiumAds.on('noAdFound', noAdFoundListener);
//unsubscribe
adexiumAds.off('noAdFound', adReceivedListener);
Ad found and redirected:
javascript
adexiumAds.on('adRedirected', () => {
alert('clicked and redirected');
});
Ad rendered and displayed
javascript
adexiumAds.on('adDisplayed', () => {
alert('Ad Displayed');
});
Ad closed by user
javascript
adexiumAds.on('adClosed', () => {
alert('Ad adClosed');
});
Ad playback completed user viewed ad.
javascript
adexiumAds.on('adPlaybackCompleted', () => {
alert('adPlaybackCompleted');
});
Method .off works for each event, do not forget to pass listener. adexiumAds.off('eventName', listenerFunction);
To check if task is completed send S2S postback to this URL:
http
GET https://bid.tgads.live/task/check/{widgetId}/{taskId}
taskId = id from callback adReceivedListener(ad) {ad.id} Response:
json
{
"done": false
}
How Ad looks like?
You can use our Example bot to see all formats: @AdexiumExampleBot