Трекинг конверсий для Telegram-ботов и Telegram Mini Apps (TMA)
Эта инструкция показывает, как передавать конверсии из вашего Telegram-бота или Telegram Mini App в Adexium.
В ссылку t.me нельзя добавить свои query-параметры, поэтому идентификатор клика передаётся внутри стартового параметра Telegram. Стартовый параметр допускает только латинские буквы, цифры, _ и - (до 64 символов), поэтому идентификатор клика ставится после префикса: adexium__[CLICK_ID]. Сохраняйте двойное подчёркивание — по нему значение удобно разделить обратно.
Пошаговая инструкция
1. Создайте рекламную кампанию
Создайте новую кампанию в кабинете Adexium.
2. Добавьте идентификатор клика в ссылку кампании
Используйте ссылку, которая соответствует тому, что вы продвигаете.
Telegram-бот — start=:
https://t.me/your_bot?start=adexium__[CLICK_ID]Telegram Mini App — startapp=:
https://t.me/your_bot/your_app?startapp=adexium__[CLICK_ID]Замените your_bot (и your_app) на реальные имена. [CLICK_ID] Adexium подставит в момент клика.
3. Получите и сохраните идентификатор клика
Бот. Когда пользователь открывает ссылку, Telegram отправляет вашему боту команду /start с параметром:
/start adexium__d95c746d-31c7-4183-8fa7-42ce39b65e47Возьмите всё, что после adexium__, и сразу сохраните вместе с пользователем — параметр приходит только один раз, при открытии ссылки.
Mini App. Для ссылок startapp= Telegram не присылает /start. Параметр попадает в Mini App как start_param внутри initData (в JavaScript: Telegram.WebApp.initDataUnsafe.start_param). Отправьте initData на свой бэкенд, проверьте подпись, как описано в документации Telegram, возьмите из start_param всё, что после adexium__, и сохраните вместе с пользователем.
4. Отправьте конверсию
Когда пользователь совершил целевое действие, вызовите постбэк со своего бэкенда:
GET https://go.atechspace.live/conversion?click_id=[CLICK_ID]&event_type=level1&key=ВАШ_КЛЮЧЗамените [CLICK_ID] на сохранённое значение, а ВАШ_КЛЮЧ — на ключ постбэка вашего аккаунта (см. ниже). Для более глубоких событий используйте event_type=level2 / level3:
| Событие | Значение |
|---|---|
level1 | Регистрация / установка (по умолчанию) |
level2 | Депозит |
level3 | Повторный депозит |
5. Ключ постбэка
Параметр key подтверждает, что постбэк отправили именно вы. Идентификаторы кликов видны площадкам и приложениям, на которых крутится ваша реклама, поэтому без ключа любой, кто их собрал, мог бы присылать конверсии по вашим кампаниям.
- Ключ есть на странице Tracking — готовый URL постбэка уже содержит его — и в Аккаунт → Безопасность.
- Передавайте его в query-строке, даже если шлёте POST. Ключ в теле запроса игнорируется.
- Держите его на сервере: не в сообщениях бота, не в коде Mini App и не в клиентском JavaScript.
- Ключ можно перевыпустить в любой момент в Аккаунт → Безопасность. Предыдущий работает ещё 7 дней — успейте за это время обновить постбэк.
Пример работы (Mini App)
- Ссылка в кампании:
https://t.me/my_game_bot/game?startapp=adexium__[CLICK_ID] - Фактический переход:
https://t.me/my_game_bot/game?startapp=adexium__d95c746d-31c7-4183-8fa7-42ce39b65e47 - Бэкенд Mini App: проверяет
initData, читаетstart_paramи сохраняетclick_id = d95c746d-31c7-4183-8fa7-42ce39b65e47для этого пользователя. - Постбэк при регистрации:
GET https://go.atechspace.live/conversion?click_id=d95c746d-31c7-4183-8fa7-42ce39b65e47&event_type=level1&key=ВАШ_КЛЮЧ
Конверсии от подписок на Telegram-каналы отслеживаются иначе — см. Трекинг конверсий (каналы).