Telegram Mini Apps Widget Integration Guide

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

Basic Integration

Integration in automatic mode:

<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):

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:

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:

[{
    "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:

const noAdFoundListener = () => {
    console.log('no ad found');
};

// subscribe
adexiumAds.on('noAdFound', noAdFoundListener);

//unsubscribe
adexiumAds.off('noAdFound', adReceivedListener);

Ad found and redirected:

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

Ad rendered and displayed

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

Ad closed by user

adexiumAds.on('adClosed', () => {
    alert('Ad adClosed');
});

Ad playback completed user viewed ad.

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:

GET https://bid.tgads.live/task/check/{widgetId}/{taskId}

taskId = id from callback adReceivedListener(ad) {ad.id} Response:

{
  "done": false
}

How Ad looks like?

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

React Integration

use-adexium-hook.ts

import * as React from 'react';
import type { AdexiumInstance, AdexiumAd, AdFormat } from '../../../@types/adexium';

type TAdexiumProps = {
  widgetId: string;
  format?: AdFormat;
  onAdReceived?: (ad: AdexiumAd) => void;
  onNoAdFound?: () => void;
  onReward?: () => void;
};

export function useAdexium({
  widgetId,
  onAdReceived,
  onNoAdFound,
  onReward,
  format = 'interstitial',
}: TAdexiumProps) {
  const adexiumRef = React.useRef<AdexiumInstance | null>(null);

  const handleAdReceived = React.useCallback(
    (ad: AdexiumAd) => {
      adexiumRef.current?.displayAd(ad);
      onAdReceived?.(ad);
    },
    [onAdReceived],
  );

  const handleNoAdFound = React.useCallback(() => {
    onNoAdFound?.();
  }, [onNoAdFound]);

  const handleAdPlaybackCompleted = React.useCallback(() => {
    onReward?.();
  }, [onReward]);

  React.useEffect(() => {
    if (!window.AdexiumWidget) {
      console.warn('AdexiumWidget script not loaded');
      return;
    }

    const adexium = new window.AdexiumWidget({
      wid: widgetId,
      adFormat: 'interstitial',
      debug: true,
    });

    adexiumRef.current = adexium;

    adexium.on('adReceived', handleAdReceived);
    adexium.on('noAdFound', handleNoAdFound);
    adexium.on('adPlaybackCompleted', handleAdPlaybackCompleted);

    return () => {
      adexium.off('adReceived', handleAdReceived);
      adexium.off('noAdFound', handleNoAdFound);
      adexium.off('adPlaybackCompleted', handleAdPlaybackCompleted);

      adexium.destroy?.();
      adexiumRef.current = null;
    };
  }, [widgetId, handleAdReceived, handleNoAdFound, handleAdPlaybackCompleted]);

  return React.useCallback(() => {
    adexiumRef?.current?.requestAd(format);
  }, [format]);
}

adexium.d.ts

export type AdFormat = 'interstitial' | 'push-like' | 'video';

type EventType =
  | 'adReceived'
  | 'noAdFound'
  | 'adDisplayed'
  | 'adRedirected'
  | 'adClosed'
  | 'adPlaybackCompleted';

interface AdexiumInitParams {
  wid: string;
  adFormat: AdFormat;
  debug?: boolean;
  firstAdImpressionIntervalInSeconds?: number;
  adImpressionIntervalInSeconds?: number;
  isFullScreen?: boolean;
}

export interface AdexiumAd {
  creativeUrl: string;
  notificationUrl: string;
  clickUrl: string;
  buttonText: string;
  title: string;
  adFormat: AdFormat;
  description: string;
}

export interface AdexiumInstance {
  autoMode(): void;
  requestAd(format: AdFormat): void;
  displayAd(ad: AdexiumAd): void;
  on(event: EventType, callback: (data: AdexiumAd) => void): void;
  off(event: EventType, callback: (data: AdexiumAd) => void): void;
}

declare global {
  interface Window {
    AdexiumWidget: {
      new (opt: AdexiumInitParams): AdexiumInstance;
    };
  }
}

tsconfig.json

{
  "compilerOptions": {
        ...propertis
  },
  "include": ["adexium.d.ts"]
}

index.html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"
    />
    <meta http-equiv="imagetoolbar" content="no" />
    <title>Your Telegram Mini app</title>
    <script src="https://telegram.org/js/telegram-web-app.js?56"></script>
    <script
      type="text/javascript"
      src="https://cdn.tgads.space/assets/js/adexium-widget.min.js"
    ></script>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/app/main.tsx"></script>
  </body>
</html>