SDK и API Pixora Ads для разработчиков

Выберите форматы при подключении площадки и передайте их на модерацию. Статика и видео — виды креатива; native, interstitial и rewarded — сценарии показа. Отдельного метода showVideo() нет: сервер подбирает подходящий креатив.

В Mini App реклама работает внутри интерфейса партнёра. Переход по рекламной кнопке добровольный; после закрытия рекламы пользователь возвращается к вашему экрану. В ботах основной формат — сообщение после полезного ответа с оплатой за переход; в каналах — рекламный пост с CPM или CPC. Кнопка ведёт к рекламодателю. JavaScript SDK предназначен для Mini App, а не сообщений.

Доход площадки и бонус зрителю — разные вещи. Для монетизации без наград выберите native или interstitial. Обычный показ учитывается после видимости не менее 50% креатива в течение непрерывной секунды в активном окне; видео должно воспроизводиться. Итог подтверждает сервер с учётом лимитов, бюджета и доступности кампании.

Для новой интеграции используйте SDK 1.8.1: init() и выбранный метод показа. Старые create()/mount() сохранены для совместимости.

1. Откройте «Монетизация → Рекламная сеть» и выберите Mini App, бота или публичный канал.
2. Укажите название, Telegram-ссылку и описание с тематикой и аудиторией. Для Mini App используйте ссылку бота или прямую ссылку t.me/bot/appname. Выберите native, interstitial и/или rewarded до модерации. Место размещения опишите в тексте: отдельного поля для него нет.
3. Подтвердите управление: токеном бота для ботов/Mini Apps; правами администратора для канала. Проверка токена подтверждает управление ботом, а место рекламы проверяет модератор.
4. Для Mini App и бота после одобрения создайте API-ключ и храните его только на сервере. Для автоматических постов в канале отдельный сервер и API-ключ не нужны: сохраните настройки публикаций и проверьте права бота.
5. Запустите тест ниже, подключите свой сервер и SDK либо подготовьте объявление в кабинете. Реальные объявления доступны при активной площадке и подходящем спросе; подключение не гарантирует загрузку рекламы или доход.

Демонстрационный @pixorAds_networkbot показывает весь путь пользователя: открытие Mini App, запрос объявления через сервер и показ выбранного формата поверх интерфейса Mini App. Его можно открыть до подключения собственной площадки.

1. Откройте бота и запустите Mini App. Демонстрационный сервер подтверждает Telegram-сессию через /api/v1/ad-network/demo/session.
2. SDK обращается к /api/v1/ad-network/demo/offer на том же origin. Секретный ключ площадки остаётся только на сервере.
3. Если подходящего оплаченного объявления нет, демонстрационное приложение показывает ознакомительное видео. Это собственный пустой экран площадки, не рекламный просмотр: за него не списываются средства и не начисляются награды или доход.

1// Demo only: run after loading pixorads-publisher.js inside Telegram.2const session = await fetch("/api/v1/ad-network/demo/session", {3  method: "POST",4  credentials: "same-origin",5  headers: { "Content-Type": "application/json" },6  body: JSON.stringify({ init_data: window.Telegram.WebApp.initData })7});8if (!session.ok) throw new Error("Telegram session could not be verified");9const { csrf_token, publisher_id } = await session.json();10const placement = window.PixorAdsPublisher.init({11  element: document.getElementById("pixorads"),12  endpoint: "/api/v1/ad-network/demo/offer",13  csrfToken: csrf_token,14  publisherId: publisher_id,15  language: "ru"16});17await placement.showNative();

Добавьте скрипт один раз в HTML. В endpoint укажите адрес своего сервера на том же origin. API-ключ в браузер не передаётся. До init() передайте Telegram.WebApp.initData на свой backend: он должен проверить подпись и срок действия, создать сессию, а при cookie-авторизации вернуть CSRF-токен для параметра csrfToken. Публичный publisherId возьмите в карточке площадки. Примеры ниже — native без награды; для других сценариев откройте «Методы показа». В React передайте CSRF-токен пропсом и вызывайте destroy() при удалении компонента.

1<!-- Render this page AFTER your backend verifies the Telegram session. -->2<!-- Your backend inserts its session CSRF token into this meta tag. -->3<meta name="csrf-token" content="YOUR_SESSION_CSRF_TOKEN">4<script src="https://pixora-ads.com/sdk/pixorads-publisher.js"></script>5<div id="pixorads"></div>6<script type="module">7  const placement = window.PixorAdsPublisher.init({8    element: document.getElementById("pixorads"),9    endpoint: "/api/pixorads/offer",10    csrfToken: document.querySelector('meta[name="csrf-token"]').content,11    publisherId: "YOUR_PUBLIC_MINIAPP_PUBLISHER_ID",12    trackAudience: false,13    personalized: false,14    language: "ru"15  });16  const state = await placement.showNative();17  if (state.status === "error") console.warn(state.code);18  // empty: no ad available. Continue the app; do not retry in a loop.19  // On screen removal: placement.destroy();20</script>

Выберите один пример ниже. Скрипт SDK уже должен быть загружен, а ваш сервер — проверить Telegram-сессию. Замените publisherId на публичный ID площадки; csrfTokenFromYourSession — CSRF-токен вашей сессии, не API-ключ. /api/pixorads/offer — маршрут, который вы создаёте на своём сервере.

1// Prerequisites: SDK loaded, your session verified, <div id="ad-slot"></div>.2const ads = window.PixorAdsPublisher.init({3  publisherId: "YOUR_PUBLIC_MINIAPP_PUBLISHER_ID",4  endpoint: "/api/pixorads/offer",5  csrfToken: csrfTokenFromYourSession,6  element: document.getElementById("ad-slot"),7  language: "ru",8  trackAudience: false, // Enable explicitly if you measure app activity.9  personalized: false10});1112const state = await ads.showNative();13if (state.status === "empty") {14  // No matching ad. Continue your app normally; try later.15} else if (state.status === "error") {16  console.warn("Ad unavailable:", state.code);17}18// ready means rendered, NOT a paid impression.19// Keep ads alive while the card is visible.20// When removing this screen: ads.destroy();

Что возвращают методы

1{2  shown: true,              // Viewer handshake completed; NOT proof of payment3  completed: false,         // true only for completed rewarded viewing4  impression_confirmed: true // Ordinary viewer confirmation, when available5  // receipt, session_id: present when supplied by the viewer6  // test:true => {shown:false, completed:false, test:true}; no overlay or payout7}

Одновременно открывается только одно рекламное окно. Не запускайте showNative() и полноэкранный метод параллельно на одном контроллере. При no_fill продолжайте работу приложения; не подменяйте обещанную награду обычной рекламой. После показа не вызывайте destroy() до закрытия окна или удаления экрана.

Для showNative() и showInterstitial() этот раздел не нужен: пользовательскую награду выдавать не требуется. В rewarded PixorAds подтверждает просмотр; монеты, жизни или другой дополнительный бонус вашего приложения начисляет ваш backend.

1. Получите receipt из результата showRewarded() после закрытия окна. Это непрозрачное подтверждение, а не сумма награды.
2. Передайте receipt своему авторизованному серверу. Он вызывает reward/verify с ключом этой площадки и сверяет telegram_id с пользователем своей сессии.
3. Одной транзакцией сохраните уникальный receipt_id и выдайте настроенный на сервере бонус. При повторной отправке верните прежний результат без второго начисления.

1// Inside YOUR authenticated, CSRF-protected reward route.2// req.user.telegramId must come from a verified session, never the request body.3const response = await fetch("https://pixora-ads.com/api/v1/ad-network/publisher-api/reward/verify", {4  method: "POST",5  headers: {"Content-Type": "application/json", "X-PixorAds-Key": process.env.PIXORADS_PUBLISHER_KEY},6  body: JSON.stringify({receipt: req.body.receipt}),7  signal: AbortSignal.timeout(8000)8});9if (!response.ok) throw new Error("Reward not verified");10const proof = await response.json();11if (!proof.rewarded || String(proof.telegram_id) !== String(req.user.telegramId)) {12  throw new Error("Wrong viewer");13}14// YOUR database transaction (required; not implemented by this snippet):15// 1. Insert (receipt_id, your_user_id) into a ledger with UNIQUE(receipt_id).16// 2. On a new row, grant YOUR server-configured internal bonus.17// 3. On duplicate, return the existing result for the same user.18// Commit both operations together, then return 2xx to the browser.19// Never take a reward amount from req.body or credit proof.reward as app coins.

Ответ: rewarded, receipt_id, session_id, publisher_id, telegram_id, operation_id, reward, currency, completed_at. Receipt действует 7 дней и привязан к площадке. Проверка не переводит деньги. При недоступности сервера повторяйте отправку того же receipt; не заставляйте пользователя смотреть рекламу заново.

Когда нужен onReward

onReward({receipt, session_id}) вызывается сразу после подтверждения просмотра, пока рекламное окно ещё открыто. Это альтернатива обработке receipt после закрытия. SDK не ждёт завершения вашего async callback и не повторяет его при ошибке: обработайте ошибку и повторную отправку сами. Если используете оба пути, единая проверка receipt_id на сервере обязательна. События onEvent и переход по CTA не разрешают начислять бонус.

Суммы API — целые внутренние единицы: XTR / 1000 = ★; RUB / 1000 = ₽; USD / 1 000 000 = $. Например, reward:70 при currency:XTR — это 0,07 ★. В offer viewer_reward/viewer_currency — награда зрителю; reward и publisher_amount — суммы в валюте кампании. publisher_income — оценка дохода площадки в USD, окончательная сумма фиксируется после подтверждения; ни одна из них не задаёт число монет в вашем приложении.

Ваш backend авторизует пользователя, ограничивает частоту запросов и запрашивает объявление у PixorAds. Ответ передаётся виджету как JSON. Для одного логического запроса используйте один Idempotency-Key при повторных попытках, для нового объявления — новый ключ.

1curl https://pixora-ads.com/api/v1/ad-network/publisher-api/offer \2  -H "X-PixorAds-Key: $PIXORADS_PUBLISHER_KEY" \3  -H "Idempotency-Key: unique-logical-request-id" \4  -H "Content-Type: application/json" \5  -d '{"language":"ru","format":"native"}'

1// Node.js 22+ / Express. Keep this code on YOUR SERVER.2// app, requireYourSession, verifyYourCsrf and yourRateLimit3// belong to your app. Implement them before exposing the route.4import { randomUUID } from "node:crypto";56app.post("/api/pixorads/offer", requireYourSession,7  verifyYourCsrf, yourRateLimit, async (req, res) => {8    res.set("Cache-Control", "no-store");9    const language = req.body?.language ?? "en";10    const context_token = req.body?.context_token ?? "";11    // Legacy create().mount() omits format; preserve the API's auto default.12    const format = req.body?.format ?? "auto";13    if (!["ru", "en"].includes(language)) return res.status(400).json({error:{code:"invalid_language"}});14    if (typeof context_token !== "string" || context_token.length > 2048) return res.status(400).json({error:{code:"invalid_viewer_context"}});15    if (!["auto", "native", "interstitial", "rewarded"].includes(format)) return res.status(400).json({error:{code:"invalid_format"}});16    // Reuse this ID if you retry this upstream request.17    const requestId = randomUUID();18    try {19      const response = await fetch(20        "https://pixora-ads.com/api/v1/ad-network/publisher-api/offer",21        {22          method: "POST",23          headers: {24            "Content-Type": "application/json",25            "X-PixorAds-Key": process.env.PIXORADS_PUBLISHER_KEY,26            "Idempotency-Key": requestId27          },28          body: JSON.stringify({ language, context_token, format }),29          signal: AbortSignal.timeout(8000)30        }31      );32      const retryAfter = response.headers.get("Retry-After");33      if (retryAfter) res.set("Retry-After", retryAfter);34      const payload = await response.json();35      // Preserve structured error.code so the SDK can show useful diagnostics.36      res.status(response.status).json(payload);37    } catch {38      res.status(503).json({ error: { code: "upstream_unavailable" } });39    }40  });

При замене или отзыве ключа старый ключ и созданные им ссылки перестают работать. Обновите переменную окружения и создайте новые размещения. Условия начатого сеанса сохраняются, но новые действия просмотра проверяют текущий статус и версию ключа.

Основной формат для ботов — реклама после полезного ответа с оплатой за подтверждённый переход. Токен BotFather остаётся на сервере владельца. Отдельная регистрация зрителя не нужна.

Настройки, согласование объявлений, ставки и история дохода — в карточке бота, раздел «Реклама в переписке». Просмотры с наградой остаются дополнительным форматом с отдельной интеграцией.

Добавьте публичный канал; ваш аккаунт и бот PixorAds должны быть администраторами. После модерации проверьте права на публикацию и удаление постов. В настройках канала выберите оплату просмотров (CPM, по умолчанию) или подтверждённых переходов (CPC). Задайте минимальный доход и лимит результата на пост. Автопубликация или согласование доступны в обоих режимах.

CPM оплачивает счётчик Telegram за первые 24 часа, включая пересылки. Это не уникальный охват или досмотр. CPC оплачивает подтверждение перехода кнопкой на коротком экране без регистрации; просмотры, предпросмотры и повторные переходы одному рекламодателю в каналах за 24 часа бесплатны. Отпечаток браузера — сочетание IP и User-Agent, а не доказательство уникального человека. Награды читателю нет.

Расчёт после 24 часов, затем удержание по условиям кампании. Курс, сумма, оплаченные просмотры или переходы и срок освобождения дохода видны в истории постов. Ставки и доли каналов регулируются отдельно от Mini App; действующие условия показаны в разделе дохода площадок.

1// Load /sdk/pixorads-offerwall.js first.2const demo = new PixorAdsOfferwall.DemoClient();3const { items } = await demo.catalog();4const attempt = await demo.start(items[0].id, "demo-1");5await demo.check(attempt.id); // demo_completed; paid=false; no receipt6demo.reset();

Offerwall 1.3 · Подключение, тест без списаний, бонусы и диагностика — в одном кабинете.

Один каталог заданий: готовый экран, компонент Mini App и API для собственного интерфейса или Telegram-бота. Поддерживаются подписки на публичные каналы и вступления в группы. Для проверки бот PixorAds должен быть администратором целевого чата. Также доступны первый запуск бота и действия в Mini Apps с подтверждением сервера рекламодателя. Для них требуется успешный тест интеграции. Также доступны реакции в публичных группах, неанонимные опросы PixorAds, новые Premium-бусты, переходы на сайты, сёрфинг и задания с отчётами, включая маркетплейсы. Доступность сайтов зависит от настроек сервиса. Отдельные форматы покупок и многоэтапные задания пока не поддерживаются.

1. Подготовьте площадку

В разделе «Мои площадки» добавьте площадку, подтвердите управление и дождитесь модерации. В блоке «Задания и бонусы» выберите награду, настройте уведомления и включите приём заданий. Партнёрский трафик получает только кампании, для которых рекламодатель явно включил этот источник.

• Награда PixorAds: пользователь получает денежную награду после регистрации; площадка — долю комиссии платформы. Стартовая доля: 50% комиссии.
• Награда площадки: пользователь получает ваши монеты или доступ, а площадка — долю цены результата. Стартовая доля: 80%. Вы самостоятельно начисляете внутренние бонусы.

Доли настраиваются и фиксируются для задания при старте. Доход площадки учитывается в USD по зафиксированному курсу и удерживается после окончательной проверки (по умолчанию 24 часа). Срок сохранения подписки показывается отдельно. Подтверждение действия ещё не означает доступность денег к выводу.

Реферальные начисления по заданиям оплачиваются из оставшейся доли платформы после выплаты паблишеру. Они не уменьшают согласованную награду пользователя или доход площадки.

2. Выберите подключение

Перед включением откройте «Монетизация → Offerwall → Подключение». Сохраните настройки, создайте учебное задание и завершите его. Событие содержит test=true, user_id=null и нулевой денежный доход. Его нельзя начислять реальному пользователю. При изменении настроек тест нужно повторить.

С webhook тест приходит на сохранённый адрес с обычной HMAC-подписью. Без webhook получите GET /publisher-api/tests. Сервер подтверждает обработку через POST /publisher-api/tests/{conversion_id}/ack с X-PixorAds-Key. HTTP 2xx сам по себе не подтверждает начисление бонуса. Учебное событие доступно 24 часа.

Готовый экран: скопируйте Telegram-ссылку из настроек оффервола. Она подходит для Mini Apps, ботов и постов каналов. Источник сохраняется; площадка не становится реферером автоматически.

1<script src="https://pixora-ads.com/sdk/pixorads-offerwall.js"></script>2<pixorads-task publisher-id="YOUR_PUBLISHER_UUID" theme="light">3</pixorads-task>

Компонент подключается внутри Telegram Mini App с подписанным initData. Используется идентификатор бота, подтверждённого для площадки. API-ключ в браузер передавать нельзя. Цветовая тема — light/dark; высота — CSS-переменная --pixorads-offerwall-height.

1const client = new PixorAdsOfferwall.Client({ publisherId: "YOUR_PUBLISHER_UUID", telegramInitData: Telegram.WebApp.initData });2// Show terms and obtain consent before connect().3const { items, history, options } = await client.connect({ accepted: true });4// items already honor the publisher's task_types on the server.5// Show an empty state when items is empty; always render history separately.6// Call only when the user chooses a task from items.7async function startSelectedTask(campaignId, retryKey) {8  const task = await client.start(campaignId, retryKey);9  const destination = await client.open(task.id);10  return { task, url: destination.url };11}12// Open the returned protected URL; offer a separate Check button.13async function checkTask(attemptId) {14  return client.check(attemptId);15}16// Do not grant a reward based on a JavaScript event.

База API — https://pixora-ads.com/api/v1/offerwall: добавляйте к ней сокращённые пути /viewer/... и /publisher-api/... из этого раздела. В Client({baseUrl}) передавайте только HTTPS-origin, например https://pixora-ads.com, без пути, query или hash.

При уходе с экрана вызовите client.disconnect(): запросы отменятся с кодом disconnected, viewer-токен будет удалён. Перед новой работой получите согласие и подключитесь заново. После потери ответа перечитайте историю; повторяйте start или отправку отчёта с исходным ключом, поскольку сервер мог уже сохранить запрос. Автоматического повтора в SDK нет.

3. API для бота

Готовые примеры: команды /bonus и /bonusbalance, кнопки выполнения и проверки, повторная сверка после перезапуска, тест подключения и защита от повторных бонусов. Работают через опрос API, без публичного webhook.

• Python 3.11+ · aiogram 3 · httpx
• Node.js 24+ · Telegraf 4

В начале каждого файла — команда запуска и переменные окружения. В примерах бонусы записываются в отдельный SQLite-баланс. Для вашей игровой валюты перенесите начисление и UNIQUE(conversion_id) в одну транзакцию вашей БД; ACK отправляйте только после её фиксации. Не запускайте второй polling-процесс поверх работающего бота: перенесите обработчики в его приложение.

Сервер бота использует отдельный ключ площадки в заголовке X-PixorAds-Key. Сначала запросите сессию по Telegram ID. Если verified=false, покажите verification_url: пользователь один раз подтверждает Telegram-аккаунт и условия на готовом экране. Нельзя подставлять произвольный ID и получать за него деньги. Подтверждение действительно сутки; серверные запросы этот срок не продлевают.

1import os, httpx2BASE = "https://pixora-ads.com/api/v1/offerwall"3KEY = os.environ["PIXORADS_KEY"]45async def get_tasks(telegram_user_id):6    async with httpx.AsyncClient(timeout=20) as api:7        r = await api.post(BASE + "/publisher-api/session",8            headers={"X-PixorAds-Key": KEY},9            json={"telegram_id": telegram_user_id})10        r.raise_for_status()11        session = r.json()12        if not session["verified"]:13            return session  # Show verification_url as a button.14        token = session["viewer_token"]15        r = await api.get(BASE + "/viewer/catalog",16            headers={"Authorization": "Bearer " + token})17        r.raise_for_status()18        return {"verified": True, "token": token, **r.json()}1920# Call only after the user selects a task.21async def start_task(token, campaign_id, retry_key):22    async with httpx.AsyncClient(timeout=20) as api:23        r = await api.post(BASE + "/viewer/start",24            headers={"Authorization": "Bearer " + token,25                     "Idempotency-Key": retry_key},26            json={"campaign_id": campaign_id})27        r.raise_for_status()28        return r.json()2930# Send title, reward and conditions. POST /viewer/attempts/{id}/open31# with the viewer token and use its url; for reports use hosted_url.32# A separate Check callback POSTs /viewer/attempts/{task_id}/check.33# Keep tokens on your server and bind callbacks to the same user.34# Store retry_key before the request and reuse it on retries.35# If items is empty, continue the ordinary bot flow.

У пользователя один отдельный слот коротких заданий и до пяти одновременно взятых заданий с отчётом: карты, маркетплейсы и расширенные задания учитываются суммарно. Проверка отчёта и ожидание доставки не занимают лимит. Уже взятые работы, вернувшиеся на доработку или из доставки, сохраняются. Пока лимит достигнут, новые выдачи недоступны. Каталог не резервирует бюджет, повторный запуск той же кампании на другой площадке не создаёт вторую выплату.

При старте обрабатывайте HTTP 409 с кодом task_assignment_limit: достигнут лимит заданий с отчётом. task_quick_assignment_limit означает занятый слот короткого задания. Покажите понятное сообщение и сохраните карточку; не переключайте пользователя на другое выполнение автоматически. Эти ошибки не создают новую выдачу или резерв. После освобождения места повторите старт. При сетевой ошибке повторяйте тот же ключ команды.

4. Начисляйте бонус только на сервере

Настройте публичный HTTPS webhook. Секрет подписи находится в настройках оффервола. Подпись X-PixorAds-Signature = HMAC-SHA256(secret, timestamp + '.' + исходные байты тела); timestamp — X-PixorAds-Timestamp. Проверяйте подпись постоянным временем и допустимое отклонение времени (например 5 минут). Не пересобирайте JSON перед проверкой.

• completed — действие обнаружено, идёт удержание подписки. Ранний бонус допустим только при заранее включённом режиме advance;
• qualified — окончательная проверка пройдена: можно один раз начислить внутренние бонусы;
• revoked — проверка удержания не пройдена, выплаты нет;
• paid — доход площадки освобождён из удержания.

Перед начислением запросите GET /publisher-api/rewards/{conversion_id}. Сверьте telegram_id, reward_mode=partner, test=false и reward_eligible=true. Начислите reward_units из этого ответа один раз. После фиксации своей транзакции отправьте POST /publisher-api/rewards/{conversion_id}/ack с {reference: 'идентификатор вашего начисления'}. Повторяйте ACK с тем же reference при сетевой ошибке. Это подтверждение отражается у пользователя и в аналитике; движение денег PixorAds оно не запускает.

5. Гибкие бонусы

Можно задать фиксированное число бонусов либо курс «бонусов за $1 дохода площадки». Количество округляется вниз, применяется ограничение минимума и максимума. Акционный множитель действует до указанного срока. Всё фиксируется при старте; цена рекламодателя и денежное распределение не меняются. Предварительный бонус в каталоге может измениться до старта при смене настроек или курса.

По умолчанию бонус выдаётся после окончательной проверки. В режиме advance площадка выдаёт свой бонус после первой проверки на собственный риск: если пользователь не сохранит подписку, доход площадки отменится. PixorAds не списывает уже использованные внутренние бонусы. Денежную награду PixorAds и освобождение дохода это не ускоряет.

Ключ начисления — conversion_id. Сохраняйте его и награду в одной транзакции своей БД с UNIQUE-ограничением. event_id защищает от повторной обработки события. Уведомления могут приходить повторно и не по порядку. Отвечайте 2xx только после сохранения. До 12 попыток доставки; причины ошибок и ручной повтор — в кабинете площадки.

Если используете receipt из окончательного результата, передайте его своему серверу: POST /publisher-api/reward/verify с ключом площадки. Сверьте telegram_id и conversion_id с пользователем своей системы. Receipt не заменяет защиту от повторного начисления. Без webhook периодически проверяйте историю и окончательные результаты.

1{2  "campaign_id": "CAMPAIGN_UUID",3  "attempt_token": "px_ATTEMPT_TOKEN",4  "event_id": "your-stable-event-id",5  "telegram_id": 123456789,6  "event_name": "tutorial_complete",7  "occurred_at": "2026-10-06T10:05:00Z",8  "first_seen_at": "2026-10-06T10:01:00Z",9  "status": "completed",10  "reason": null11}

Статистика и ограничения

Передайте placement при создании Client или атрибут placement в компоненте; в API — при запросе сессии. Допустимы латинские буквы, цифры, _ и -, до 40 символов. Виджет отмечает видимость карточки при отображении не менее 50%. В собственном интерфейсе вызовите client.visible([campaignId]) после фактического показа; не вызывайте его при загрузке каталога. В ботах видимость сообщения неизвестна — этот счётчик остаётся пустым.

Обращение привязано к конкретному выполнению: POST /viewer/attempts/{id}/ticket, тело {message: 'описание'}, либо client.support(id, message). Ответ появляется в history[].ticket. Паблишер видит обращения своей площадки; оператор отвечает в админке «Рекламная сеть → Обращения Offerwall».

Кабинет показывает начатые задания, повторные проверки, подтверждённые результаты, отмены, расходы рекламодателя и доход площадки. Период относится к дате начала задания. Загрузка каталога не считается показом рекламы, уникальным охватом или оплачиваемым действием. В расчёт оплаты входят только окончательно подтверждённые результаты.

Измерения включаются через init({publisherId, trackAudience:true}); у init() это значение по умолчанию. Укажите false, если измерения не нужны. trackVisit() использует подписанный Telegram initData не старше часа. Инициализация только в рекламном блоке измеряет его посетителей, а не всю аудиторию приложения.

Вызывайте trackVisit() при значимых возвращениях в приложение, без частого опроса. Повторные люди исключаются сервером. recorded:false означает, что наблюдение не записано; это не ошибка рекламного показа. trackAudience:false отключает автоматическую отправку, но не запрещает явный вызов trackVisit().

Боты отправляют реальную активность через POST /api/v1/ad-network/publisher-api/activity с {telegram_id} и серверным X-PixorAds-Key. Это данные партнёра, не доказательство оплаченного просмотра. Каналы обновляют подписчиков в кабинете после проверки прав администратора; подписчики и рекламный охват — разные показатели.

Показываем отдельно активность за 24 часа / 7 / 30 дней, уникальных зрителей, видимые показы и завершённые просмотры. Прогноз требует 7 полных UTC-дней измерений каждой выбранной площадки; для фильтров без подходящей истории прогноз не подставляется. Аудитории измеренных площадок дедуплицируются; подписчики каналов не суммируются. Группы меньше 20 человек скрыты рекламодателю.

Расскажите пользователям об измерениях. Используйте personalized:true только после разрешения на использование существующей анкеты PixorAds. Не подменяйте подписанные initData данными initDataUnsafe. Наблюдения хранятся с HMAC-идентификатором до 90 дней.

Ниже загружается настоящий SDK с test: true. Никакие объявления не запрашиваются, деньги и статистика не меняются. Нажмите кнопку внутри карточки. Такой же режим можно включить на своей странице; endpoint для него не требуется.

1window.PixorAdsPublisher.mount({2  element: document.getElementById("pixorads"),3  language: "ru",4  test: true5});

Новые интеграции: init() → выбранный метод → destroy() при удалении экрана. Legacy create() требует element; mount() использует auto-выбор формата и возвращает Promise состояния. PixorAdsPublisher.mount(options) — сокращённый вызов без доступного контроллера; для управления жизненным циклом используйте init() или create().

Среда запуска и CSP

Для живого embedded-показа нужен HTTPS и запуск внутри Telegram с подписанным initData не старше часа. В обычном браузере используйте test:true; initDataUnsafe не подтверждает личность. Истёкшие данные обновляются новым запуском Mini App, а не изменением auth_date.

В Content-Security-Policy разрешите https://pixora-ads.com для script-src, frame-src и connect-src; для медиа карточки — img-src и media-src. Сохраните необходимые разрешения вашего приложения. Если CSP ограничивает стили, проверьте совместимость: SDK задаёт inline-стили карточки и оверлея. API-ключ никогда не передаётся в браузер.

TypeScript: сохраните .d.ts в папку, включённую в tsconfig, и используйте window.PixorAdsPublisher. Это типы глобального скрипта, не npm-модуль. Официального npm-пакета пока нет.

1curl https://pixora-ads.com/api/v1/ad-network/publisher-api/offer \2  -H "X-PixorAds-Key: $PIXORADS_PUBLISHER_KEY" \3  -H "Idempotency-Key: unique-logical-request-id" \4  -H "Content-Type: application/json" \5  -d '{"language":"ru","format":"native"}'

Пример ответа

Ниже сокращённый пример rewarded. Возвращайте SDK полный JSON сервера без изменения URL, формата и полей учёта. Для native/interstitial billing = confirmed_impression и есть impression_url. reward и publisher_amount — целые внутренние единицы: XTR и RUB делите на 1000, USD — на 1 000 000. Награда зрителю: viewer_reward/viewer_currency. Оценка дохода площадки в USD: publisher_income.

1{2  "source": "pixorads",3  "placement_id": "<placement UUID>",4  "title": "<advertisement title>",5  "text": "<plain text>",6  "disclosure": "Реклама · Ad · PixorAds",7  "url": "https://t.me/pixoradsbot?startapp=net_<32 hex characters>",8  "expires_at": "<ISO 8601 timestamp>",9  "format": "rewarded",10  "billing": "completed_rewarded_session",11  "currency": "XTR",12  "reward": 70,13  "publisher_amount": 114}15// No suitable demand: { "source": "none", "monetag_enabled": false }16// Rewarded response excerpt, not a complete offer to return from your backend.17// Example: 70 XTR minor units = 0.07 Stars; 1 = 0.001 Stars.18// Ordinary: billing:"confirmed_impression", reward:0, impression_url present.19// Forward the FULL upstream JSON unchanged; never build it from this excerpt.

Обычное размещение действует 5 минут, rewarded — 24 часа; ориентируйтесь на expires_at. Idempotency-Key — до 80 символов: один на логический запрос. Для rewarded повтор возвращает прежний ответ. Для обычного объявления повтор уже выданного запроса даёт placement_already_issued: запросите новое размещение с новым ключом. Повторы не должны создавать цикл запросов.

В карточке площадки показаны выданные сеансы, подтверждённые завершения, доход на удержании и начисленный доход. Обычные подтверждённые показы учитываются отдельно от завершений rewarded; запрос offer, отрисовка карточки или клик сами по себе не подтверждают доход. Доход начисляется в USD. Для Mini App: 80% в действующую акцию, затем 70%; для новых кампаний каналов: 90%, затем 88%; для CPC в ботах — отдельный тариф. Текущие ставки показаны в разделе дохода площадок. Для обычной рекламы — от оплаченного показа; для Rewarded — после награды зрителю. Для каналов цена и доля фиксируются при создании кампании, курс — при резервировании поста. Для Mini App условия фиксируются при выдаче размещения, сумма USD — при подтверждении. Старые RUB и Stars сохраняются отдельно; вывод USD — только криптовалютными методами. Ставки зависят от аукциона и доступной рекламы. При ограничениях выплата дохода может оставаться на проверке.

Для обращения укажите ID площадки, время ошибки, HTTP-статус и код. Не присылайте API-ключ или токен бота.

Выберите форматы при подключении площадки и передайте их на модерацию. Статика и видео — виды креатива; native, interstitial и rewarded — сценарии показа. Отдельного метода showVideo() нет: сервер подбирает подходящий креатив.

В Mini App реклама работает внутри интерфейса партнёра. Переход по рекламной кнопке добровольный; после закрытия рекламы пользователь возвращается к вашему экрану. В ботах основной формат — сообщение после полезного ответа с оплатой за переход; в каналах — рекламный пост с CPM или CPC. Кнопка ведёт к рекламодателю. JavaScript SDK предназначен для Mini App, а не сообщений.

Доход площадки и бонус зрителю — разные вещи. Для монетизации без наград выберите native или interstitial. Обычный показ учитывается после видимости не менее 50% креатива в течение непрерывной секунды в активном окне; видео должно воспроизводиться. Итог подтверждает сервер с учётом лимитов, бюджета и доступности кампании.

Для новой интеграции используйте SDK 1.8.1: init() и выбранный метод показа. Старые create()/mount() сохранены для совместимости.

Передавайте достижения рефералов в Keitaro, Binom v2 или свой сервер. Это исходящая аналитика: она не меняет выплаты и не заменяет Offerwall webhook или серверное подтверждение Pixel.

1. Подключите трекер

Партнёры → Ссылки → Постбеки: выберите трекер, вставьте его публичный HTTPS endpoint, добавьте цели и сохранённые ссылки. Посмотрите сформированный запрос, проверьте доставку и включите подключение. Один трекер можно использовать для нескольких ссылок; у каждой ссылки одно подключение.

2. Сохраните ID клика трекера

1# Keitaro2https://pixora-ads.com/api/v1/referrals/track/YOUR_LINK_CODE?tracker_click_id={subid}34# Binom5https://pixora-ads.com/api/v1/referrals/track/YOUR_LINK_CODE?tracker_click_id={clickid}

Скопируйте свой link code из сохранённой ссылки; макрос заменит трекер при переходе. tracker_click_id — внешний идентификатор (до 128 символов), click_id — отдельный внутренний ID Pixora. Промежуточная ссылка сохраняет внешний ID и открывает выбранный сайт, бота или Mini App. Прямая Telegram-ссылка с фиксированными sub_id не передаёт динамический ID клика трекера.

3. Выберите цели и суммы

До 24 целей на подключение. amount — сумма события, payout — доход партнёра: пополнение реферала на 1 000 ₽ не становится доходом рефовода. Денежный payout по умолчанию формирует только commission. Валюты не смешиваются; Stars не переводятся в рубли или доллары. В API настроек amount_minor — строка целого числа: RUB и XTR используют 1 000 единиц, USD — 1 000 000; в исходящем postback amount и payout уже десятичные строки в своей валюте.

Keitaro получает стабильный tid для каждой цели и события; повтор не должен добавлять вторую конверсию. В Binom выделите отдельные event1…event24 и одну валюту дохода RUB или USD. Адаптер передаёт абсолютные значения событий и накопленного дохода, disable_upsell=1 и disable_postback=1. Не складывайте их повторно правилами своего трекера.

Свой endpoint: GET или POST

1https://tracker.example/pixora?click={tracker_click_id}&goal={goal_id}&event={event}&amount={amount}&currency={currency}&payout={payout}&payout_currency={payout_currency}

Макросы разрешены только в query-значениях: tracker_click_id, click_id, event_id, goal_id, event, link_id, sub_id_1…sub_id_5, amount, currency, payout, payout_currency, occurred_at. Записывайте их в фигурных скобках. Имена status, goal и amount_minor макросами не являются. event_id и tracker_click_id добавляются и к пользовательскому GET, даже если не указаны в шаблоне.

POST отправляет фиксированный JSON с этими полями, schema_version=1, test_mode, event_type и corrects_event_id. Это не произвольный шаблон тела. Сохраняйте event_id с UNIQUE-ограничением в той же транзакции, что и результат обработки; на повтор отвечайте 2xx. Корректировка event_type=correction ссылается на исходное событие через corrects_event_id. Учебные test_mode=true события не начисляйте реальным пользователям.

Доставка, повторы и журнал

Предпросмотр не отправляет запрос. Тест доставки использует синтетический px_test_… ID; HTTP 2xx подтверждает только ответ endpoint, а не конверсию в трекере. Для полной проверки пройдите свою ссылку из трекера и достигните выбранной цели. Журнал показывает событие, статус и причину ошибки без раскрытия секретных параметров.

Сетевые ошибки, 429 и 5xx повторяются с задержкой, до 8 автоматических попыток за цикл. Другие 4xx и перенаправления останавливают доставку. Ручной повтор использует прежний event_id, URL и данные. Неуспешное событие блокирует более новые события этого внешнего клика: восстановите endpoint и повторите его. Изменение настроек действует на будущие переходы и не переотправляет историю. Первоначальная реферальная привязка сохраняется.

API управления: /api/v1/referrals/postbacks — только для авторизованного владельца. GET — список, POST — создание; /{id}: GET и PUT; /{id}/events — журнал; /preview и /{id}/preview — просмотр запроса; /{id}/test и /events/{event_id}/retry — явная доставка. Создание, сохранение, тест и повтор требуют Idempotency-Key (1–96 символов); обновление требует актуальную version. Ключ площадки X-PixorAds-Key здесь не используется.