Ссылки, плейсхолдеры и шаги воронки

Как это работает

1. Проект — куда вести трафик (сайт, бот, Mini App) и шаги после перехода: «Запуск → Регистрация → Оплата».
2. Ссылки — https://utm.mgram.biz/abc1234 с UTM-метками на каждый источник: рассылка, Показы, канал, блогер.
3. Переход — MGRAM запоминает клик, подставляет плейсхолдеры в адрес и ведёт человека дальше.
4. Шаги — бот, сайт или сервер отправляет шаги с click_id; панель считает воронку и выручку по каждой ссылке и метке.

Плейсхолдеры в адресе

Пишутся в фигурных скобках прямо в адресе: https://t.me/your_bot?start={click_id} или https://site.ru/?cid={click_id}&src={utm_source}.

{click_id}

номер перехода — передавайте дальше по воронке: в /start бота, в адрес сайта

{utm_source} … {utm_term}

UTM-метки ссылки

{sub1} … {sub5}

значения из адреса перехода: …/abc1234?sub1=vk

{project}, {link}

номер проекта и код ссылки

{country}

страна посетителя

{ts}

время перехода, Unix

Шаги воронки — API

POST https://utm.mgram.biz/api/v1/events, заголовок Authorization: Bearer utm_sk_… — ключ записи проекта (выдаётся в панели один раз).

step обязательно

ключ шага: латиница, цифры, _ (до 32); новый шаг сам добавится в воронку (до 20)

click_id

номер перехода из плейсхолдера — связывает шаг со ссылкой и источником. Можно передать и код ссылки: бот запущен по t.me/bot?start=код (например, из заказа запусков MGRAM) — шаг засчитается этой ссылке

link

код ссылки, если перехода не было (например, бот открыт по своей ссылке)

user_id

ваш идентификатор пользователя (до 128 символов)

value, currency

сумма шага и валюта

event_id

ваш номер события — повтор не задвоится

unique

true — один раз на переход или пользователя

meta

ваши данные, до 20 полей

Пачкой: {"events": […]} до 100 событий. Ответ: {"ok": true, "id": 123, "attributed": true}.

import os, requests

MGRAM_UTM_KEY = os.environ.get("MGRAM_UTM_KEY", "utm_sk_…")

def track(step, click_id=None, user_id=None, value=None):
    requests.post("https://utm.mgram.biz/api/v1/events", timeout=5,
                  headers={"Authorization": f"Bearer {MGRAM_UTM_KEY}"},
                  json={"step": step, "click_id": click_id, "user_id": user_id, "value": value, "unique": True})

track("register", click_id=click_id, user_id="42")

# адрес проекта: https://t.me/your_bot?start={click_id}
from aiogram.filters import CommandStart, CommandObject
import aiohttp, os

MGRAM_UTM_KEY = os.environ.get("MGRAM_UTM_KEY", "utm_sk_…")

async def track(step, click_id, user_id, value=None):
    async with aiohttp.ClientSession() as s:
        await s.post("https://utm.mgram.biz/api/v1/events", headers={"Authorization": f"Bearer {MGRAM_UTM_KEY}"},
                     json={"step": step, "click_id": click_id, "user_id": str(user_id), "value": value, "unique": True})

@router.message(CommandStart(deep_link=True))
async def start(message, command: CommandObject):
    await track("start", command.args, message.from_user.id)   # command.args — это {click_id}

const MGRAM_UTM_KEY = process.env.MGRAM_UTM_KEY || "utm_sk_…";

async function track(step, { clickId, userId, value } = {}) {
  await fetch("https://utm.mgram.biz/api/v1/events", {
    method: "POST",
    headers: { Authorization: `Bearer ${MGRAM_UTM_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ step, click_id: clickId, user_id: userId, value, unique: true }),
  });
}

<?php
$ch = curl_init("https://utm.mgram.biz/api/v1/events");
curl_setopt_array($ch, [
  CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . (getenv("MGRAM_UTM_KEY") ?: "utm_sk_…"), "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(["step" => "register", "click_id" => $clickId, "user_id" => (string)$userId, "unique" => true]),
]);
curl_exec($ch);

curl -X POST https://utm.mgram.biz/api/v1/events \
  -H "Authorization: Bearer utm_sk_…" -H "Content-Type: application/json" \
  -d '{"step":"register","click_id":"CLICK_ID","user_id":"42","unique":true}'

<!-- адрес проекта: https://your-site.ru/?mgram_cid={click_id} -->
<script src="https://utm.mgram.biz/t.js" data-key="utm_pk_…" data-step="visit" async></script>
<script>window.mgramUtm && window.mgramUtm("lead")  // шаг отмечен «сайт» в проекте</script>

Данные перехода и браузер

Данные перехода

GET https://utm.mgram.biz/api/v1/clicks/{click_id} с ключом записи — ссылка, UTM-метки, sub-параметры, страна и время

Из браузера

публичный ключ и скрипт t.js; шаги, отмеченные «сайт» в проекте, засчитываются один раз на переход

Лимиты

до 50 проектов, до 500 ссылок в проекте, 1 200 событий в минуту, 100 в запросе

Хранение

IP не храним: уникальные посетители считаются по суточному хэшу