Skip to content

Интеграция в Telegram Mini App ​

Как показывать рекламу Adexium внутри вашего Telegram Mini App (TMA).

Создайте плейсмент ​

В кабинете паблишера выберите New placement → Telegram Mini App и заполните:

  • Mini App link — публичная ссылка t.me на ваш Mini App. Её проверяет наша команда; после создания изменить нельзя.
  • Bot ID — числовой ID бота, которому принадлежит Mini App: часть до : в токене от @BotFather (токен 1234567890:AAH… → ID 1234567890). Вводите только число, никогда не токен. Это должен быть бот из вашей ссылки: рекламные сети по нему проверяют, что показы идут из вашего настоящего Mini App.
  • Blocked ad categories — категории рекламы, которые вы не хотите показывать своим пользователям.

После сохранения на странице плейсмента появится готовый код с уже подставленным Placement ID (WID).

Базовая интеграция (автоматический режим) ​

  1. Добавьте скрипт Telegram в <head> вашего Mini App. Если вы используете @telegram-apps/sdk, этот шаг не нужен.
html
<script src="https://telegram.org/js/telegram-web-app.js?56"></script>
  1. Добавьте скрипт Adexium и включите автоматический режим:
html
<script type="text/javascript" src="https://cdn.tgads.space/assets/js/adexium-widget.min.js"></script>
<script type="text/javascript">
    document.addEventListener('DOMContentLoaded', () => {
        const adexiumAds = new AdexiumWidget({
            wid: 'YOUR_WIDGET_ID',
            adFormat: 'interstitial', // или 'push-like'
            firstAdImpressionIntervalInSeconds: 10, // необязательно, по умолчанию 10: первая реклама через 10 с после открытия приложения
            adImpressionIntervalInSeconds: 45, // необязательно, по умолчанию 45: не чаще одного показа в 45 с
            debug: true, // тестовая реклама на каждый запрос — уберите на продакшене
            isFullScreen: false // необязательно: принудительно полноэкранная реклама
        });
        adexiumAds.autoMode(); // показывать рекламу автоматически; не вызывайте, если показываете вручную
    });
</script>

Ручная интеграция ​

Чтобы показать рекламу в выбранный вами момент (например, по нажатию кнопки), запросите её и покажите сами:

js
document.addEventListener('DOMContentLoaded', () => {
    const adexiumAds = new AdexiumWidget({
        wid: 'YOUR_WIDGET_ID',
        adFormat: 'interstitial',
        debug: true // уберите на продакшене
    });
    const button = document.getElementById('button');

    button.onclick = () => {
        adexiumAds.requestAd('interstitial');
    };

    adexiumAds.on('adReceived', (ads) => {
        adexiumAds.displayAd(ads); // показываем рекламу в наших стилях
    });

    adexiumAds.on('noAdFound', () => {
        // для этого пользователя рекламы сейчас нет
    });
});

Выберите метод по тому, зачем пользователь смотрит рекламу:

js
adexiumAds.requestAd('interstitial');         // пользователь ничего не получает за просмотр
adexiumAds.requestRewardedAd('interstitial'); // пользователь получает вознаграждение за просмотр

Что приходит в adReceived ​

Слушатель получает список из одного объявления:

json
[
  {
    "id": "64c286d8-04a2-4f4b-ac80-e455d8cbe020",
    "creativeUrl": "https://cdn.adexium.tech/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? Play now!",
    "adFormat": "interstitial",
    "description": "Blast Cannon: aim, fire, win!"
  }
]

id — идентификатор объявления, по нему проверяется клик. Видеокреатив приходит с "adFormat": "video" — displayAd покажет его сам.

События ​

На любое событие можно подписаться через on и отписаться через off. В off передавайте ту же функцию, что и в on.

СобытиеКогда срабатывает
adReceivedРеклама найдена; слушатель получает список объявлений
noAdFoundДля этого пользователя сейчас нет рекламы
requestAdErrorЗапрос рекламы не прошёл (ошибка сети или таймаут)
adDisplayedРеклама показана на экране
adRedirectedПользователь кликнул по рекламе и перешёл
adClosedПользователь закрыл рекламу
adPlaybackCompletedПользователь досмотрел рекламу до конца (таймер истёк)
javascript
const adReceivedListener = (ads) => {
    adexiumAds.displayAd(ads);
    const adId = ads[0].id;
};
const noAdFoundListener = () => {
    console.log('no ad found');
};

// подписаться
adexiumAds.on('adReceived', adReceivedListener);
adexiumAds.on('noAdFound', noAdFoundListener);

// отписаться
adexiumAds.off('adReceived', adReceivedListener);
adexiumAds.off('noAdFound', noAdFoundListener);

Проверить, был ли клик ​

Для заданий вида «открой рекламу и получи награду» вызывайте этот URL со своего сервера:

http
GET https://bid.tgads.live/task/check/{widgetUid}/{adId}
  • {widgetUid} — ваш Placement ID (WID), то же значение, что вы передаёте в wid.
  • {adId} — id объявления из adReceived.

Ответ:

json
{
  "done": false
}

done становится true, когда пользователь кликнул по рекламе. До этого — false, поэтому запрос можно повторять.

Задания без виджета ​

Рекламу можно запросить и со своего сервера, чтобы показать её как задание в вашем интерфейсе.

http
POST https://bid.tgads.live/bid-request

Тело запроса:

json
{
    "wid": "YOUR_WIDGET_ID",
    "adFormat": "push-like",
    "language": "en",
    "ip": "8.8.8.8",
    "isPremium": true,
    "firstName": "test",
    "lastName": "test",
    "telegramId": "123456789",
    "platform": "android",
    "tonConnected": false,
    "motivated": true
}
  • wid — ваш Placement ID (WID).
  • tonConnected — необязательно.
  • motivated — true, потому что задание вознаграждается.

Ответ имеет тот же вид, что в разделе Что приходит в adReceived, а если рекламы нет — пустой список []. Клик проверяйте через /task/check по id объявления.

Как выглядит реклама ​

Все форматы можно посмотреть в нашем примере: @AdexiumExampleBot

Интеграция в React ​

use-adexium.ts

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

type TAdexiumProps = {
  widgetId: string;
  format?: AdFormat;
  onAdReceived?: (ads: 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(
    (ads: AdexiumAd[]) => {
      adexiumRef.current?.displayAd(ads);
      onAdReceived?.(ads);
    },
    [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: format,
    });

    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);
      adexiumRef.current = null;
    };
  }, [widgetId, format, handleAdReceived, handleNoAdFound, handleAdPlaybackCompleted]);

  // Вызовите возвращённую функцию, чтобы запросить рекламу за вознаграждение, например по кнопке «Смотреть и получить».
  return React.useCallback(() => {
    adexiumRef.current?.requestRewardedAd(format);
  }, [format]);
}

adexium.d.ts

typescript
// Форматы, которые можно запросить. Полученное объявление может прийти и с 'video' (видеокреатив).
export type AdFormat = 'interstitial' | 'push-like';

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

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

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

export interface AdexiumInstance {
  autoMode(): void;
  requestAd(format: AdFormat): Promise<AdexiumAd[]>;
  requestRewardedAd(format: AdFormat): Promise<AdexiumAd[]>;
  displayAd(ads: AdexiumAd[]): void;
  on(event: EventType, callback: (...args: any[]) => void): void;
  off(event: EventType, callback: (...args: any[]) => void): void;
}

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

tsconfig.json

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

index.html

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" />
    <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/main.tsx"></script>
  </body>
</html>