Skip to content

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