Интеграция в 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…→ ID1234567890). Вводите только число, никогда не токен. Это должен быть бот из вашей ссылки: рекламные сети по нему проверяют, что показы идут из вашего настоящего Mini App. - Blocked ad categories — категории рекламы, которые вы не хотите показывать своим пользователям.

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

Базовая интеграция (автоматический режим)
- Добавьте скрипт Telegram в
<head>вашего Mini App. Если вы используете@telegram-apps/sdk, этот шаг не нужен.
<script src="https://telegram.org/js/telegram-web-app.js?56"></script>- Добавьте скрипт Adexium и включите автоматический режим:
<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>Ручная интеграция
Чтобы показать рекламу в выбранный вами момент (например, по нажатию кнопки), запросите её и покажите сами:
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', () => {
// для этого пользователя рекламы сейчас нет
});
});Выберите метод по тому, зачем пользователь смотрит рекламу:
adexiumAds.requestAd('interstitial'); // пользователь ничего не получает за просмотр
adexiumAds.requestRewardedAd('interstitial'); // пользователь получает вознаграждение за просмотрЧто приходит в adReceived
Слушатель получает список из одного объявления:
[
{
"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 | Пользователь досмотрел рекламу до конца (таймер истёк) |
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 со своего сервера:
GET https://bid.tgads.live/task/check/{widgetUid}/{adId}{widgetUid}— ваш Placement ID (WID), то же значение, что вы передаёте вwid.{adId}—idобъявления изadReceived.
Ответ:
{
"done": false
}done становится true, когда пользователь кликнул по рекламе. До этого — false, поэтому запрос можно повторять.
Задания без виджета
Рекламу можно запросить и со своего сервера, чтобы показать её как задание в вашем интерфейсе.
POST https://bid.tgads.live/bid-requestТело запроса:
{
"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
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
// Форматы, которые можно запросить. Полученное объявление может прийти и с '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
{
"compilerOptions": {},
"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" />
<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>