Документація

PWA та Web Push

PWA-лендинг — це локальний лендинг, який Orbitra рендерить у повноцінний веб-застосунок: вітрину «магазину застосунків», маніфест і service worker. Разом із модулем Web Push це дозволяє вирощувати базу підписників прямо на вітрині і надсилати їм push-и — все самостійно, без зовнішніх сервісів (FCM використовується лише як транспорт на Android, Apple — як транспорт на iOS; ключі і база — ваші).

У цьому документі: конструктор PWA, встановлення застосунку, прив'язка домену, інструментування воронки, база підписників, повідомлення (ручні та подієві), cron доставки і усунення проблем.


1. PWA-лендинг: що це і як працює

1.1 Як усе влаштовано всередині

config_json містить "pwa": true. Кліковий роутер, ротація потоків і клоакинг ставляться до нього як до будь-якого іншого локального лендинга — нових типів немає.

index.html (вітрина у стилі Google Play), manifest.webmanifest і sw.js.

лише всередині scope маніфеста, тому кореневий URL не використовується.

вітрину, тож push-підписка, бекони воронки і стрибок на оффер приписуються реальному кліку.

картку Chrome (Android 94+ / desktop 105+): крім базових полів він оголошує id, lang, description (з розв'язаними макросами {value}) і display_override, а також перелічує кожен скріншот вітрини, що проходить обмеження картки Chrome (кожна сторона 320–3840px, співвідношення сторін ≤ 2.3), як screenshots з форм-фактором narrow/wide. Картка Install readiness** редактора показує той самий вердикт наживо.

Firefox/Opera на Android бачать кроки з меню браузера (iOS бачить кроки Safari, поки ios_flow = instruction), а in-app webview (Instagram, Facebook, TikTok, generic WebView) отримують картку «відкрийте цю сторінку у вашому браузері», яку можна закрити — воронка під нею продовжує працювати.

1.2 Конструктор

Landings → Add PWA (або «Duplicate» на наявному). Головні блоки редактора:

БлокЩо налаштовує
GeneralНазва застосунку, slug, група, іконка і скріншоти (через Content Gallery), категорія, розробник, мова, версія, «updated»
StoreОпис (з макросами {value}), теги, гістограма рейтингу, відгуки, «what's new», бейджі (verified, glow, живий лічильник), світла/темна тема, колірна схема
ScreenВнутрішній екран застосунку після встановлення: тип, заголовок, текст, кнопка, зображення, власний HTML/JS
ActionsДія кнопки встановлення: на оффер / у кампанію / на URL / нікуди (action_target), таймери авто-редиректу
PushУвімкнення push-підписки на екрані застосунку (push_enabled)
DomainПрив'язка домену (див. п. 2) + оффер для прямого домену
ReadinessЖивий чекліст того, як виглядатиме нативна інсталяційна картка: іконка, опис, розміри скріншотів, push-ключі, прив'язка домену

Кнопка Preview рендерить чернетку конфіга продакшн-рендерером — живе прев'ю вітрини і екрана (платформа auto/iOS) без збереження.

1.3 Воронка та бекони

Сторінка вітрини надсилає однопіксельні бекони, які пишуться в клік:

запуск у standalone на iOS);

(щонайбільше раз на 10 хвилин на клік);

push-підписки;

(nokey / unsupported / insecure / denied / dismissed / error / timeout).

Усі колонки видимі у деталях кліка — головному інструменті діагностики воронки: трекер сам називає причину, логи браузера не потрібні.

1.4 Push-підписка живе у service worker

Підписка працює повністю всередині згенерованого sw.js (orbitraSubscribe): сторінка лише надсилає повідомлення воркеру і йде на оффер. Це свідомо — на iOS перший, холодний pushManager.subscribe може тривати десятки секунд, і підписка не мусить залежати від того, скільки користувач пробуде на сторінці. Воркер також:

боці push-сервісу, оновлення VAPID-ключа);

налаштуваннями трекера (self-heal) — повторне відкриття застосунку лагодить підписку без перевстановлення;

(фокусує наявне вікно і переходить на data.url).

Плейсхолдер {vapid_public} у sw.js підставляється в момент віддачі файлу, а не при генерації — зміна VAPID-ключа доходить до вже встановлених застосунків без перегенерації статичних файлів.

1.5 RENDERER_VERSION

Кожна зміна рендерера підіймає RENDERER_VERSION (core/PwaLanding.php). При наступному перегляді лендинга трекер звіряє маркер версії у відрендерених статичних файлах і сам перегенеровує застарілі файли — без ручного перезаливання на сервер.


2. Прив'язка домену до PWA

Домен можна прив'язати до PWA напряму: візит на https://domain.com/ відкриває вітрину з кореня, без стрибка через кампанію і /lander/ — чисте інсталяційне посилання.

доменах.

кнопка «Offer» на вітрині все одно веде на оффер через /?_lp=1 з атрибуцією.

прив'язку; прив'язка перемагає index_campaign_id на корені.

реальні кліки в заархівовану системну кампанію orbitra-pwa-organic — вона створюється автоматично і не видна у списку кампаній. Повторні візити з живою кукою не плодять дублів.


3. Web Push: база, ключі, надсилання

3.1 VAPID-ключі та контакт

Сторінка Push Base (панель → Push):

  1. Заповніть контакт — mailto:[email protected] або https://…. Без

справжнього контакту генерація ключів заблокована: Apple (web.push.apple.com) перевіряє claim sub у JWT і відповідає 403 BadJwtToken на адреси-заглушки.

  1. Натисніть Generate keys. Ключі зберігаються в налаштуваннях трекера

(vapid_public_key / vapid_private_key / vapid_private_pem); шифрування і підпис — чистий PHP + openssl (RFC 8291 + RFC 8292), без composer.

  1. Key rotation питає підтвердження: наявні підписки перестають бути

чинними, але кожен пристрій тихо перепідписується при наступному відкритті застосунку (self-heal); база відновлюється сама.

Діагностична стрічка на сторінці показує: чи є ключі, публічний ключ, контакт (з попередженням, якщо стоїть дефолтний), вік останнього ping воркера і останні коди помилок доставки.

3.2 Вкладка «Subscribers»

Таблиця push_subscriptions: id, клік, endpoint, країна, мова, UA, статус (active / expired), created, останній показ. Можливості:

GDPR-сценарій);

і cron**, миттєво. Відповіді декодуються чесно: 403 — підказка про невірний VAPID-контакт, 404/410 — підписка мертва, решта — код помилки сервісу. Це найшвидший спосіб протестувати весь трубопровід (ключі → JWT → push-сервіс → пристрій).

Підписники множаться через перевстановлення і перепідписки (endpoint змінює push-сервіс) — старі рядки протікають самі через 404/410 при відправці, окрема чистка не потрібна. Перед розсилкою перевірте «свіжість» підписника за його кліком (деталі кліка показують лендинг і UA встановлення).

3.3 Вкладка «Messages»

Повідомлення — це шаблони розсилок. Два види:

install (встановлення PWA), lead, sale, із затримкою delay_seconds секунд від події.

Поля повідомлення: title (≤250), body (≤400), іконка (URL, зручно з Gallery), банерне зображення (URL — Android Chrome показує його як велику картинку на сповіщенні; iOS мовчки ігнорує), посилання переходу (click-through), сегмент, таргетинг за країною і мовою, прапорець «active».

Сегменти рахуються з лічильників конверсій підписника в момент постановки в чергу:

СегментХто отримує
allусі активні підписники
reg0без реєстрації
reg1dep0зареєстрований, без депозиту
reg1dep1зареєстрований і з депозитом

Таргетинг (міграція 60) звужує будь-який сегмент далі в момент постановки в чергу: countries — список ISO-кодів через кому, звірений з гео підписника (US, DE), languages — дволітерні коди мови браузера, звірені за первинним субтегом (en збігається з підписником, записаним як en-US). Порожній список = без обмежень. Сміттєві записи відкидаються при збереженні, ніколи не зберігаються.

Body підтримує макроси, що розгортаються в момент надсилання: {variant1|variant2} (випадковий вибір, вкладеність ≤10), {Random=(X,Y)}, {subid} та інші клікові макроси — одне повідомлення дає кожному отримувачу власний текст.

3.3.1 Push-кліки та CTR повідомлення

Кожне сповіщення, яке показує SW, несе id доставки у своєму data (subid, message_id, sid). Тап по ньому запускає один бекон (/pixel.gif?action=pwa&kind=pushclick) до навігації, тож тап рахується, навіть якщо браузер одразу йде на оффер:

рахунком на 10 хвилин, як і відкриття) — це ROI-число: підписники → кліки → конверсії, усе на одній воронці;

Push clicks по кожному повідомленню з відсотком переходів;

3.3.2 Відписка

Само сповіщення несе кнопку дії Unsubscribe (локалізована, вшита у SW лендинга; iOS ігнорує дії — тап по сповіщенню там усе одно відкриває). Натискання POSTить endpoint браузера на публічний /push_unsubscribe ingest, який ставить is_active = 0 (ідемпотентно; ключі лишаються, тож панель може повторно активувати). Є і окрема публічна сторінка /push-unsubscribe?endpoint=<urlencoded> — вона рендерить кнопку підтвердження (деактивація — POST за нею, тож prefetch-посилання нікого не відпише) і її можна лінкувати звідки завгодно.

Згенерований SW також віддає спеціальну офлайн-сторінку для невдалих навігацій (локалізована, з кнопкою Retry) замість застарілої закешованої вітрини — закешована сторінка магазину надсилала б бекон зі старим click id, а її CTA все одно не може працювати офлайн.

3.4 Надсилання: черга та cron

Панель сама нічого не надсилає. Кнопка «Send now» на рядку повідомлення ставить у чергу (push_queue) один запис на кожного активного підписника сегмента, з захистом від дублів, і відповідає «Queued: N».

Доставку виконує cron-воркер cli/push_cron.php — щохвилини:

* * * * * www-data php /var/www/orbitra/cli/push_cron.php --quiet >> /var/www/orbitra/var/logs/push.log 2>&1

Рядок встановлюється install.sh автоматично (маркер # orbitra-push); перевірка: crontab -u www-data -l | grep orbitra-push. Воркер: flock від паралельних запусків, батчі ≤300, ретрай через 300 секунд, 429 поважає Retry-After, 401/403 — один ретрай зі свіжим JWT, 404/410 — підписка протікає, 5xx/мережа — назад у чергу. Подієві повідомлення запускаються тим самим воркером через курсор у налаштуваннях.

Здоров'я черги показане на стрічці над списком повідомлень: pending/done/failed і час останнього ping воркера. Якщо ping не тікає — cron не встановлений або не працює, і доставки не буде.

3.5 Що означає «надіслано»

201 від push-сервісу означає «конверт прийнято», а не «доставлено». Push-сервіс не може зламати шифрування (E2E): він відповідає 201 і мовчки викидає повідомлення, якщо пристрій його так і не прочитає. Фінальний суддя — лише телефон. Контрольований ланцюжок перевірки:

  1. Push Base → Subscribers → Send на рядку → банер «accepted»;
  2. на пристрої: шторка сповіщень (банер міг мовчки пройти, поки

застосунок був відкритий);

  1. якщо 201, але тиша — див. п. 4.

4. Діагностика та типові проблеми

Підписки немає взагалі — деталі кліка: push_fail_reason називає причину (unsupported = немає Push API — webview Telegram/Chrome на iOS; insecure = немає HTTPS; nokey = VAPID не налаштований; denied = відмовлено; timeout = повільна мережа — підписка прийде при наступному відкритті через self-heal).

iOS — лише Safari, і лише з домашнього екрана. Web push на iOS працює за таких умов: iOS ≥ 16.4, застосунок додано на домашній екран саме з Safari (звичайний Safari не має об'єкта Notification — підписка ніколи не створюється), домен з нормальним публічним сертифікатом. Застосунок, доданий на домашній екран з Chrome (CriOS), гарантій push не отримує: перевірте браузер встановлення за UA в деталях кліка (CriOS/… = Chrome, Version/… = Safari). Якщо не працює — перевстановіть іконку з Safari.

403 BadJwtToken при відправці — невірний VAPID-контакт: Apple відхиляє адреси-заглушки (mailto:orbitra@localhost). Введіть справжній mailto:.

201, але не доходить усім і всюди — перевірте, що сервер на найсвіжішій версії (git log --oneline -1 через sudo -u www-data): ранні збірки мали дефекти крипто-конверта (заголовок без keyid, розклад ключів не за RFC 8291), які сервіс усе одно приймав з 201. Потім контрольний експеримент: десктопний Chrome → встановіть PWA → Allow → Send: якщо на десктоп приходить, а на iPhone немає — проблема в пристрої/каналі (VPN ламає постійне з'єднання APNs; встановлення через Chrome); якщо і десктоп нічого не отримує — пишіть у підтримку з кодом помилки з діагностичної стрічки.

«Кнопки не клікаються» після оновлення панелі — майже завжди кеш браузера зі старим index.html: hard-reload (Cmd+Shift+R) або приватна вкладка.

Мовчазний cron — push_cron_last_ping_at не тікає: cron не встановлений. crontab -u www-data -l | grep orbitra-push; лог — var/logs/push.log.


5. Тести

openssl, ключ у k= збігається з підписаним ключем, record розшифровується байт-у-байт так, як це робить браузер (keyid зчитаний з ефіру), референсний вектор з бібліотеки web-push (npm) розшифровується нашим кодом, HKDF за RFC 5869, ліміти розміру record (body ≤ 4096 байтів — ліміт Apple/FCM).

піксель pushclick (тротл + push_sends.clicked_at), /push_unsubscribe і публічна сторінка відписки, RBAC.

момент віддачі, заголовок Service-Worker-Allowed.

органічні кліки, пріоритети прив'язки.

Вихід з in-app браузера (renderer v19+)

PWA неможливо встановити всередині webview FB/IG/TikTok — кожен візит у webview — гарантована втрата воронки. З увімкненим Auto-open in browser (за замовчуванням) лендинг одразу йде: Android через intent:// у Chrome (поточний URL як fallback), iOS 17+ через x-safari-https://; старіша iOS лишає картку з інструкцією. URL виходу несе click id, і зовнішній браузер продовжує той самий клік — без другого кліка, без роздвоєння воронки. Картка PWA-воронки показує attempts і success rate (повернення у справжньому браузері). На волю виходить лише грошова сторона: safe page продовжує віддавати безпечний контент.

Доставка та атрибуція конверсій

Макроси оффера в тексті push-повідомлень

{offer.value} / {offer.value1} / {offer.value2} розв'язуються з таблиці оффера по країнах (Country → бонус / фріспіни / валюта; порожня країна = універсальний fallback) за країною підписника, через оффер, на який пішов клік підписки. У редакторі повідомлення є живе прев'ю для обраної країни + оффера. Без контексту макрос лишається видимим — ніколи не стає мовчазно порожнім.

Надсилання за локальним часом підписника

Підписка зберігає IANA-часовий пояс пристрою (старі рядки: виведений з гео країни). Повідомлення з Send at subscriber's local time перечікує тихі години — за замовчуванням 23:00–08:00 локально (push_quiet_hours) — і надсилається у першу дозволену хвилину. Повторна постановка в чергу тримає рядок у pending (last_code=quiet), воно ніколи не падає.

Власні push-сповіщення оператора (PWA панелі)

Усе вищезгадане шле push підписникам лендингів. Сама панель теж є PWA (встановлюється з браузера), а Users & Profile → Profile → Push notifications дозволяє оператору отримувати web push на власні пристрої — алерти конверсій і дайджести за день/тиждень/місяць — без Telegram.

шестерні) — підвкладка Push to phone, персональна для кожного користувача; підвкладка Telegram (лише адмін) тримає чати бота і розклад дайджестів. Профіль тримає картку-покажчик; сторінка Push несе примітку «це підписники лендингів» з посиланням сюди.

той самий /sw.js. Коли браузер пропонує встановлення, у navbar з'являється пігулка Install; iOS Safari ведуть інструкції картки (Share → Add to Home Screen). Адміни можуть згенерувати спільні VAPID-ключі прямо в картці (контакт включно) — без обходу на сторінку Push.

worker. VAPID-пара ключів спільна з push-базою лендингів (сторінка Push → Subscribers → keys) — одна пара ключів, дві аудиторії; «ключів ще немає» — перша підказка картки. На iOS сповіщення працюють лише всередині встановленого застосунку.

sale, deposit, … — і ID кампаній; порожнє = усе). Надсилається синхронно з постбека, як і Telegram-алерти; endpoint 404/410 автоматично відправляє пристрій на спокій.

пн–нд, надсилається в понеділок) і щомісячний (останній повний місяць, надсилається 1-го) — кліки, конверсії, дохід, прибуток — о локальному digest_time користувача. Вікна рахуються в часовому поясі профілю користувача (безпечні щодо DST) і звіряються з UTC clicks.created_at; виключені хіти safe page викинуті точно як на дашборді (orbitraSafePagePredicate). Пропущений понеділок / 1-ге (cron лежав, дайджест щойно увімкнули) довозиться на наступному тіку. Надсилається cli/push_cron.php; маркер відправки в admin_push_digest_log унеможливлює подвійну відправку.

(міграція 69) — жорстко відокремлені від push_subscriptions (ті — відвідувачі лендингів). API-дії: admin_push_state, admin_push_subscribe, admin_push_unsubscribe, admin_push_settings_save, admin_push_test.

notificationclick (лише посилання того ж origin). Тести: php tests/admin_push_test.php.

Щотижневі та щомісячні дайджести Telegram (міграція 70)

Щоденне зведення адмінського бота обзавелося двома братами, на сторінці Notifications → Telegram: щотижневе (останній повний тиждень, надсилається в понеділок) і щомісячне (останній повний місяць, надсилається 1-го); налаштовується лише час відправки. Увесь Telegram-час — щоденний включно — читається в часовому поясі профілю першого адміна, а не серверний час. Перемикачі по кожному чату дзеркалять команди бота /weekly on|off і /monthly on|off; доставка раз на вікно зафіксована tg_digest_log (унікальний чат × період × вікно). Підсумки беруться з того самого хелпера AdminPushNotify::digestWindow()/windowStats(), яким користуються push-дайджести, тож Telegram і push ніколи не розходяться в цифрах.

← Попередній
Лендинги
Наступний →
PWA-воронка
Переглянути джерело на GitHub: github.com/fenjo26/Orbitra.link/wiki
Усі гайди
Документація

Швидкий старт: ваша перша кампанія

Короткий шлях: встановіть трекер, створіть кампанію та отримайте перші кліки й конверсії менш ніж за годину.

Читати гайд →
Документація

Встановлення та оновлення

Встановіть Orbitra на чистий сервер Ubuntu або Debian однією командою та безпечно оновлюйтеся до нових версій.

Читати гайд →
Документація

Міграція з Keitaro

Перенесіть кампанії, оффери, джерела та домени з Keitaro в Orbitra одним імпортом — що переноситься і що перевірити після нього.

Читати гайд →
Документація

Міграція з Binom

Перенесіть кампанії та потоки з Binom у Orbitra через Public API: що переноситься автоматично, а що налаштувати вручну.

Читати гайд →
Документація

Огляд можливостей

Усе, що вміє Orbitra: кампанії та потоки, клоакинг, лендинги, PWA, постбеки, витрати, звіти та інтеграції.

Читати гайд →
Документація

Кампанії та потоки

Повна довідка: налаштування кампаній, типи потоків, схеми, ротація, фільтри, тестові посилання та кожна опція з поясненням.

Читати гайд →
Документація

Клоакинг

Повна довідка з клоакингу: шари детекції, глобальні налаштування, фільтри потоку, вердикти та звіти.

Читати гайд →
Документація

Перевірка браузера

Як JS-перевірка ловить ботів, віртуальні машини та емулятори за суперечностями в браузерному оточенні.

Читати гайд →
Документація

Лендинги

Типи лендингів, макрос {offer}, JS-адаптер, LeadForge та мультиофферні лендинги — повна довідка.

Читати гайд →
Документація

PWA та Web Push

Створюйте встановлювані PWA-застосунки та збирайте push-підписників: налаштування, іконки, події та сповіщення.

Читати гайд →
Документація

PWA-воронка

Воронка візиту на PWA-лендинг: екрани до встановлення, трекінг кожного екрана, статистика показів і матриця переходів.

Читати гайд →
Документація

Конверсійні попапи

Попап із кнопкою оффера на лендингах: вкладка Popup, вертикальні шаблони, тригери показу і метрики показів та CTR.

Читати гайд →
Документація

Записи сесій і теплові карти

Реплеї реальних візитів, теплові карти кліків і скролу, ліміти сховища, приватність і запис цілих сайтів.

Читати гайд →
Документація

Галерея контенту

Повна довідка Галереї: папки, завантаження, MediaPicker у редакторах, контракти розміру, обмеження форматів і відео.

Читати гайд →
Документація

Бібліотека креативів

Креативи з витратами, доходом і ROI: синк файлів з Facebook і TikTok, дедуплікація, звіти і алерт вигорання креативів.

Читати гайд →
Документація

Зовнішні PWA та Telegram-канали

Сторонні PWA-сервіси як цілі потоків (/eflow) і Telegram-канали як оффери: funnel-бот, вступи-конверсії та атрибуція.

Читати гайд →
Документація

Постбеки та конверсії

Вхідні постбеки, статуси й типи конверсій, вихідні S2S-постбеки на джерело, черга доставки, тестер і імпорт конверсій.

Читати гайд →
Документація

Витрати

Імпорт витрат з Facebook, TikTok, Google Ads і push/pop-мереж, розподіл по кліках, агентські комісії та агрегатор доходу.

Читати гайд →
Документація

Push- і pop-мережі

Імпорт витрат із push/pop-мереж і Zone Killer: правила, що знаходять і блокують зони, які палять бюджет.

Читати гайд →
Документація

Facebook / Meta

Імпорт витрат з Meta Ads і Conversions API: токени, мапінг статусів, серверні події з дедуплікацією і діагностика.

Читати гайд →
Документація

Dolphin / Fbtool

Отримуйте витрати Facebook у трекер через API Dolphin (Fbtool) у реальному часі: API-ключ, налаштування сервісів і розподіл витрат по кліках.

Читати гайд →
Документація

Чистильник коментарів FB

Масова модерація коментарів під рекламою Meta за розкладом: набори правил, винятки, сухий прогін, журнал дій і авто-пауза.

Читати гайд →
Документація

Джерела трафіку та партнерські мережі

Два довідники, що налаштовують «краї» воронки: шаблони джерел і мереж, параметри, постбек у джерело та офферні параметри.

Читати гайд →
Документація

Звіти, логи та метрики

Дашборд, список кампаній, конструктор звітів, тренди й когорти, лог трафіку та картка кліка — і як рахується кожна метрика.

Читати гайд →
Документація

Домени та SSL

Додайте домени, наведіть DNS на сервер, отримайте безкоштовний сертифікат Let's Encrypt і розберіться з кожним перемикачем на сторінці Domains.

Читати гайд →
Документація

Cloudflare

Інтеграція з Cloudflare через API: A-записи ставляться автоматично, а з проксі SSL роздає Cloudflare — без certbot і очікування валідації.

Читати гайд →
Документація

Адміністрування

Користувачі, ролі та права по ресурсах, налаштування безпеки, гео-бази, оновлення панелі й розширення Ads Manager.

Читати гайд →
Документація

Telegram-бот

Керуйте трекером із Telegram: статистика, конверсії та сповіщення в чаті, вебхук або поллінг і алерти в канали.

Читати гайд →
Документація

MCP: ШІ-асистент у трекері

Підключіть Claude або будь-який MCP-клієнт до Orbitra й керуйте кампаніями, офферами та доменами звичайними словами.

Читати гайд →