Widget Integration Guide

Learn how to integrate ad widgets into your Telegram Mini Apps effectively.

Basic Integration

Add this script to your HTML using Your Widget ID generated after widget creation:

<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 tgAds = new TGAdsWidget({
            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 :)
        });
        tgAds.init(); // if you want to show AD in auto mode if not - do not call this method
    });
</script>

If you would like to show ad manually there are some methods and events available to use:

Request Ad Method:

tgAds.requestAd('interstitial'); // request an Ad interstitial/push-like

Ad found and received:

 tgAds.on('adReceived', (adList) => {
    tgAds.displayAd(adList); // display ad using our styles
    tgAds.redirectToAd(adList); // redirect immediately to ad click url without displaying
    // make sure you use only one of this method.
});

Response example adList:

[{
    "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! "
}]

Ad not found:

tgAds.on('noAdFound', () => {
    console.log('no ad found');
});

Ad found and redirected:

tgAds.on('adRedirected', () => {
    alert('clicked and redirected');
});

Ad rendered and displayed

tgAds.on('adDisplayed', () => {
    alert('Ad Displayed');
});

Ad playback completed user viewed ad.

tgAds.on('adPlaybackCompleted', () => {
    alert('adPlaybackCompleted');
});

How Ad looks like?

You can use our Example bot to see all formats: @TGAdsExampleBot