PWA-лендинги и Web Push
PWA-лендинг — это локальный лендинг, который Orbitra рендерит в полноценное веб-приложение: витрину «магазина приложений», манифест и service worker. Связка с модулем Web Push позволяет собрать базу подписчиков прямо на витрине и рассылать им пуши — своими силами, без внешних сервисов (FCM используется только как транспорт Android, Apple — как транспорт iOS; ключи и база — ваши).
Документ покрывает: конструктор PWA, установку приложения, привязку домена, вёрстку воронки, базу подписчиков, сообщения (ручные и событийные), крон доставки и диагностику проблем.
1. PWA-лендинг: что это и как устроено
1.1 Как это работает внутри
- PWA — обычная строка в таблице
landings(типlocal), у которой в
config_json есть "pwa": true. Кликовый роутер, ротация стримов и клоакинг работают с ним как с любым локальным лендингом — никаких новых типов.
- При сохранении конструктор генерирует в каталог лендинга три файла:
index.html (витрина в стиле Google Play), manifest.webmanifest и sw.js.
- Лендинг отдаётся по адресу
/lander/<slug>/— Chrome предлагает установку
только внутри scope манифеста, поэтому корневой URL не используется.
- Клик (строка в Click Log + куки атрибуции) пишется до редиректа на
витрину, поэтому подписка на push, beacon'ы воронки и переход на оффер атрибутируются настоящему клику.
1.2 Конструктор
Лендинги → Добавить PWA (или «Дублировать» у существующего). Основные блоки редактора:
| Блок | Что настраивает |
|---|---|
| General | Имя приложения, slug, группа, иконка и скриншоты (через Галерею контента), категория, разработчик, язык, версия, «обновлено» |
| Store | Описание (с макросами {value}), теги, гистограмма оценок, отзывы, «что нового», бейджи (verified, glow, live-счётчик), светлая/тёмная тема, цветовая схема |
| Screen | Встроенный экран приложения после установки: тип, заголовок, текст, кнопка, картинка, свой HTML/JS |
| Actions | Действие кнопки установки: на оффер / на кампанию / на URL / никуда (action_target), таймеры авто-редиректа |
| Push | Включение подписки на пуши на экране приложения (push_enabled) |
| Domain | Привязка домена (см. §2) + оффер для прямого домена |
Кнопка Preview рендерит черновик конфигурации через боевой рендерер — живой предпросмотр витрины и экрана (платформа auto/iOS) без сохранения.
1.3 Воронка и beacon'ы
Страница витрины отправляет однопиксельные beacon'ы, которые пишут в клик:
pwa_intent_at— тап по «Установить»;pwa_install_at— приложение установлено (событиеappinstalledили первый
standalone-открытие на iOS);
pwa_open_at/pwa_open_count— переоткрытия установленного приложения
(не чаще раза в 10 минут на клик);
push_prompted_at/push_declined_at/push_subscribed_at— события
подписки на пуш;
push_fail_reason— причина несостоявшейся подписки
(nokey / unsupported / insecure / denied / dismissed / error / timeout).
Все колонки видны в деталях клика — это главный инструмент диагностики воронки: трекер сам называет причину, логи браузера не нужны.
1.4 Подписка на пуш живёт в service worker
Подписка выполняется целиком внутри сгенерированного sw.js (orbitraSubscribe): страница лишь отправляет сообщение воркеру и уходит на оффер. Это осознанно — у iOS-холодный первый pushManager.subscribe может занимать десятки секунд, и подписка не должна зависеть от того, сколько пользователь находится на странице. Воркер также:
- переподписывается сам по событию
pushsubscriptionchange(ротация ключа
endpoint'а на стороне 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/ — URL установки чистый.
- Привязка настраивается в конструкторе (блок Domain) или в карточке домена.
- Один домен — не более одного PWA; один PWA можно повесить на несколько
доменов.
- Рядом с доменом выбирается оффер (
pwa_offer_id): без кампании кнопка
«Offer» на витрине всё равно ведёт на оффер через /?_lp=1 с атрибуцией.
- Приоритеты: явный
?campaign_id=или алиас кампании всегда сильнее
привязки; привязка сильнее index_campaign_id на корне.
- Органические визиты (холодный посетитель без куки клика) логируются как
настоящие клики в архивную системную кампанию orbitra-pwa-organic — она создаётся автоматически и не видна в списке кампаний. Повторные заходы с живой кукой не плодят дубликаты.
3. Web Push: база, ключи, отправка
3.1 VAPID-ключи и контакт
Страница Push Base (панель → Push):
- Заполните контакт —
mailto:[email protected]илиhttps://…. Без
реального контакта генерация ключей заблокирована: Apple (web.push.apple.com) валидирует claim sub в JWT и отвечает 403 BadJwtToken на адреса-заглушки.
- Нажмите Сгенерировать ключи. Ключи хранятся в настройках трекера
(vapid_public_key / vapid_private_key / vapid_private_pem), шифрование и подпись — чистый PHP + openssl (RFC 8291 + RFC 8292), без composer.
- Ротация ключей требует подтверждения: существующие подписки перестают
быть валидными, но каждое устройство тихо переподпишется при следующем открытии приложения (self-heal), база восстановится сама.
Полоса диагностики на странице показывает: наличие ключей, публичный ключ, контакт (и предупреждение, если стоит дефолтный), возраст последнего пинга ворнера и коды последних ошибок доставки.
3.2 Вкладка «Подписчики»
Таблица push_subscriptions: id, клик, endpoint, страна, язык, UA, статус (активна / состарилась), создана, последний показ. Возможности:
- фильтры по статусу/стране, поиск по endpoint и click_id, пагинация 50/стр;
- операции: активировать / деактивировать / удалить (жёсткое удаление —
GDPR-сценарий);
- CSV-экспорт всей базы (
;-разделитель: id;дата;статус;страна;язык;click_id;endpoint); - кнопка Send в строке — тестовый пуш конкретному подписчику **мимо очереди
и крона**, мгновенно. Ответы разбираются честно: 403 — подсказка про невалидный контакт VAPID, 404/410 — подписка мертва, остальное — код ошибки сервиса. Это самый быстрый способ проверить всю трубу (ключи → JWT → push-сервис → устройство).
Подписчики плодятся переустановками и переподписками (endpoint меняет push-сервис) — старые ряды сами состариваются через 404/410 при отправке, отдельной чистки не нужно. Перед обстрелом проверяйте «свежесть» подписчика по его клику (детали клика показывают лендинг и UA установки).
3.3 Вкладка «Сообщения»
Сообщения — шаблоны рассылки. Два вида:
- Ручные — то, что вы отправляете кнопкой;
- Событийные (kind
event) — отправляются кроном автоматически по событию:
install (установка PWA), lead, sale, с задержкой delay_seconds секунд от события.
Поля сообщения: заголовок (≤250), текст (≤400), иконка (URL, удобно из Галереи), ссылка перехода, сегмент, флаг «активно».
Сегменты считаются по счётчикам конверсий подписчика в момент постановки в очередь:
| Сегмент | Кто получает |
|---|---|
all | все активные подписчики |
reg0 | без регистрации |
reg1dep0 | есть регистрация, нет депозита |
reg1dep1 | есть регистрация и депозит |
В тексте работают макросы, которые разворачиваются в момент отправки: {вариант1|вариант2} (случайный выбор, вложенность ≤10), {Random=(X,Y)}, {subid} и другие кликовые макросы — одно сообщение даёт каждому получателю свой текст.
3.4 Отправка: очередь и крон
Панель сама ничего не рассылает. Кнопка «Отправить сейчас» в строке сообщения ставит в очередь (push_queue) по одной записи на каждого активного подписчика сегмента с защитой от дублей, и отвечает «В очередь поставлено: N».
Доставку выполняет крон-воркер 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/сеть — возврат в очередь. Событийные сообщения триггерятся тем же воркером по курсору в settings.
Здоровье очереди — в полосе над списком сообщений: pending/done/failed и время последнего пинга воркера. Если пинг не тикает — крон не установлен или не запускается, доставка стоять не будет.
3.5 Что значит «отправлено»
201 от push-сервиса — это «конверт принят», а не доставка. Push-сервис шифрование не вскрывает (E2E): он отвечает 201 и молча выбрасывает сообщение, если устройство его не прочитает. Финальный судья — только телефон. Смониторенная цепочка проверки:
- Push Base → Подписчики → Send в строке → баннер «принят»;
- на устройстве: шторка уведомлений (баннер мог тихо уйти при открытом
приложении);
- если 201, а тишина — смотрите §4.
4. Диагностика и частые проблемы
Подписки нет вообще — детали клика: push_fail_reason назовёт причину (unsupported = нет Push API — вебвью Telegram/Chrome на iOS; insecure = нет HTTPS; nokey = VAPID не настроен; denied = отказ; timeout = медленная сеть — подписка доедет при следующем открытии через self-heal).
iOS — только Safari и только с домашнего экрана. Веб-пуш на iOS работает при условиях: iOS ≥ 16.4, приложение добавлено «На экран Домой» именно из Safari (в обычной Safari объекта Notification нет — подписка не создаётся никогда), домен с нормальным публичным сертификатом. Приложение, добавленное на домашний экран из Chrome (CriOS), пуши не гарантирует: проверяйте браузер установки по UA в деталях клика (CriOS/… = Chrome, Version/… = Safari). Не работает — переустановите иконку из Safari.
403 BadJwtToken при отправке — невалидный контакт VAPID: Apple отвергает адреса-заглушки (mailto:orbitra@localhost). Впишите реальный mailto:.
201, но не приходит всем и везде — проверьте, что сервер на актуальной версии (git log --oneline -1 через sudo -u www-data): ранние сборки имели дефекты крипто-конверта (заголовок без keyid, key schedule не по RFC 8291), которые сервис принимал с 201. Затем контрольный эксперимент: десктопный Chrome → установить PWA → Allow → Send: если на десктопе приходит, а на iPhone нет — проблема в устройстве/канале (VPN рвёт постоянное соединение APNs; Chrome-установки), если и на десктопе нет — пишите в поддержку с кодом ошибки из полосы диагностики.
«Кнопки не нажимаются» после обновления панели — почти всегда кэш браузера со старым index.html: hard-reload (Cmd+Shift+R) или приватная вкладка.
Тишина крона — push_cron_last_ping_at не тикает: крон не установлен. crontab -u www-data -l | grep orbitra-push; лог — var/logs/push.log.
5. Тесты
tests/push_sender_test.php— криптография: ES256-подпись верифицируется
openssl, ключ в k= совпадает с подписанным ключом, расшифровка записи побайтово как делает браузер (keyid читается с провода), эталонный вектор от библиотеки web-push (npm) расшифровывается нашим кодом, HKDF по RFC 5869, лимиты размера записи (тело ≤ 4096 байт — лимит Apple/FCM).
tests/push_macros_test.php— макросы и сегментный SQL.tests/push_base_test.php— валидатор/push_subscribe, миграции, статика.tests/push_cron_test.php— очередь, ретраи, старение подписок.tests/pwa_landing_test.php— SW-хендлеры, подстановка{vapid_public}при
отдаче, заголовок Service-Worker-Allowed.
tests/domain_pwa_test.php— корневой рендер привязанного домена, куки,
органические клики, приоритеты привязки.
Выход из in-app браузера (рендерер v19+)
PWA нельзя установить внутри вебвью FB/IG/TikTok — каждый такой визит это гарантированная потеря воронки. С включённым «Автооткрытием в браузере» (по умолчанию) лендинг сразу уходит: Android через intent:// в Chrome (текущий URL как фолбэк), iOS 17+ через x-safari-https://; старые iOS оставляют карточку-инструкцию. URL выхода несёт click id, и внешний браузер продолжает тот же клик — второго клика и разрывов воронки нет. Карточка воронки показывает попытки и процент успешных выходов. Выходит только денежная сторона: сейф-пейдж как обслуживался, так и обслуживается.
Доставка и атрибуция конверсий
- Показано: сервис-воркер бьёт бикон в момент реального показа уведомления (
push_sends.viewed_at) — «показано %» и CTR от показов честные. - Конверсии по пушам (
core/PushAttribution.php): конверсия на клике подписчика засчитывается пушу, если пришла в окне атрибуции после клика по пушу (режимsendтоже есть) — побеждает последний клик до конверсии. Окно:push_attribution_hours(1–720, по умолчанию 72). FTD = первый депозит подписчика, повторы — редепы. Депозит остаётся и за рекламным кликом — отчёты кампаний не меняются. - Баннер предупреждает при доставке ниже 50%: эндпоинты с 404/410 отключаются сами при отправках, база лечится.
Макросы оффера в пуше
{offer.value} / {offer.value1} / {offer.value2} берутся из таблицы оффера по странам (Страна → бонус / фриспины / валюта; пустая страна — универсальный фолбэк) по стране подписчика, через оффер клика подписки. В редакторе сообщения — предпросмотр для выбранной страны и оффера. Без контекста макрос остаётся видимым — никогда пустым.
Отправка по местному времени подписчика
Подписка хранит IANA-зону устройства (старые строки — зона по гео-стране). Сообщение с «По времени подписчика» пережидает тихие часы (по умолчанию 23:00–08:00, push_quiet_hours) и уходит в первую допустимую минуту — строка остаётся pending (last_code=quiet), это не ошибка.
Push-уведомления оператору (PWA панели)
Всё вышесказанное — пуши подписчикам лендингов. Но сама панель тоже PWA (устанавливается из браузера), и Пользователи → Профиль → Push-уведомления позволяют оператору получать веб-пуши на свои устройства — алерты о конверсиях и итоги дня/недели/месяца — без Telegram.
- Где: раздел «Уведомления» (меню аватара или шестерёнка) — подвкладка
Push на телефон, личная у каждого пользователя; подвкладка Telegram (только админ) — чаты бота и расписание итогов. В Профиле осталась карточка-указатель; на странице Push — пояснение «это подписчики лендингов» со ссылкой сюда.
- Установка: панель отдаёт манифест (
<панель>?orbitra_manifest=1) и тот
же /sw.js. Когда браузер предлагает установку, в навбаре появляется кнопка «Установить»; на iOS Safari карточка подсказывает путь (Поделиться → На экран «Домой»). Админ может сгенерировать общие VAPID-ключи прямо в карточке (с контактом) — без захода на страницу Push.
- «Включить на этом устройстве» подписывает браузер через сервис-воркер
панели. VAPID-ключ общий с базой пушей лендингов (страница Push → Подписчики → ключи) — одна пара ключей, две аудитории; отсутствие ключей — первая подсказка карточки. На iOS уведомления работают только в установленном приложении.
- Алерты о конверсиях: пуш на каждый подходящий постбек (фильтры по
статусам — sale, deposit, … — и ID кампаний; пусто = всё). Отправляются синхронно из постбека, как Telegram-алерты; эндпоинт 404/410 гасит устройство автоматически.
- Дайджесты: день (сегодня), неделя (прошлая полная неделя пн–вс,
приходит в понедельник) и месяц (прошлый полный месяц, приходит 1-го) — клики, конверсии, доход, профит — в локальное digest_time пользователя. Окна считаются в часовом поясе профиля (с учётом перехода на летнее/зимнее время) и сравниваются с clicks.created_at в UTC; исключённые safe-page клики не учитываются — так же, как на дашборде (orbitraSafePagePredicate). Пропущенный понедельник / 1-е число (лежал крон, дайджест только что включили) догоняется на следующем тике. Шлёт cli/push_cron.php; маркер admin_push_digest_log исключает двойную отправку.
- Таблицы:
admin_push_subs,admin_push_settings,
admin_push_digest_log (миграция 69) — строго отдельно от push_subscriptions (это посетители лендингов). API-экшены: admin_push_state, admin_push_subscribe, admin_push_unsubscribe, admin_push_settings_save, admin_push_test.
- Ядро:
core/AdminPushNotify.php;sw.jsпанели обрабатываетpushи
notificationclick (ссылки только same-origin). Тесты: php tests/admin_push_test.php.
Итоги недели/месяца в Telegram (миграция 70)
У ежедневной сводки админ-бота появились братья — на странице Уведомления → Telegram: недельная (прошлая полная неделя, приходит в понедельник) и месячная (прошлый полный месяц, приходит 1-го); настраивается только время. Всё время в Telegram, включая дневную сводку, считается по часовому поясу из профиля первого администратора, а не по времени сервера. Переключатели по чатам дублируют команды /weekly on|off и /monthly on|off; однократность в окне гарантирует tg_digest_log (уникальность чат × период × окно). Цифры считает тот же хелпер AdminPushNotify::digestWindow()/windowStats(), что и пуш-дайджесты, поэтому Telegram и push не могут разойтись в числах.
Быстрый старт: первая кампания
Короткий путь: установите трекер, создайте кампанию и получите первые клики и конверсии меньше чем за час.
Читать гайд →ДокументацияУстановка и обновление
Установите Orbitra на чистый сервер Ubuntu или Debian одной командой и безопасно обновляйтесь до новых версий.
Читать гайд →ДокументацияМиграция из Keitaro
Перенесите кампании, офферы, источники и домены из Keitaro в Orbitra в один клик — что переносится и что проверить.
Читать гайд →ДокументацияМиграция из Binom
Перенесите кампании и потоки из Binom в Orbitra: что переносится автоматически, а что настроить вручную.
Читать гайд →ДокументацияВозможности Orbitra
Всё, что умеет Orbitra: кампании и потоки, клоакинг, лендинги, PWA, постбеки, расходы, отчёты и интеграции.
Читать гайд →ДокументацияКампании и потоки
Полный справочник: настройки кампаний, типы потоков, схемы, ротация, фильтры, тестовые ссылки и каждый параметр.
Читать гайд →ДокументацияКлоакинг
Полный справочник по клоакингу: уровни детекции, глобальные настройки, фильтры потоков, вердикты и отчёты.
Читать гайд →ДокументацияПроверка браузера
Как JS-проверка ловит ботов, виртуальные машины и эмуляторы через противоречия в окружении браузера.
Читать гайд →ДокументацияЛендинги
Типы лендингов, макрос {offer}, JS-адаптер, LeadForge и мульти-оффер лендинги — полный справочник.
Читать гайд →ДокументацияPWA-лендинги и Web Push
Собирайте устанавливаемые PWA-приложения и собирайте push-подписчиков: настройки, иконки, события и уведомления.
Читать гайд →ДокументацияPWA-воронка
Многошаговая PWA-воронка: приглашения к установке, отслеживание событий и возвратные уведомления.
Читать гайд →ДокументацияКонверсионные попапы
Показывайте реальные конверсии как попапы на странице: настройка, триггеры и размещение.
Читать гайд →ДокументацияЗаписи сессий и карта кликов
Воспроизводите реальные визиты, смотрите карты кликов и скроллов. Лимиты хранения и приватность.
Читать гайд →ДокументацияГалерея контента
Центральное хранилище иконок, скриншотов и креативов для PWA и лендингов.
Читать гайд →ДокументацияБиблиотека креативов
Храните креативы с отслеживанием по subid и тестируйте их в разных кампаниях.
Читать гайд →ДокументацияВнешние PWA и Telegram-каналы
Публикуйте PWA на внешних доменах и используйте Telegram-каналы как источник трафика.
Читать гайд →ДокументацияПостбеки и конверсии
Входящие постбеки, статусы и типы конверсий, исходящие S2S-постбеки в источник трафика.
Читать гайд →ДокументацияРасходы: импорт из рекламных кабинетов
Импорт расходов из Facebook, TikTok и Google Ads, обновление через API и крон — и как работает агрегатор доходов.
Читать гайд →ДокументацияPush и pop сети
Работа с пуш и поп источниками трафика: фиды, оптимизация зон и zone killer.
Читать гайд →ДокументацияFacebook / Meta integration
Импорт расходов из Meta Ads и Conversions API: серверные события с дедупликацией.
Читать гайд →ДокументацияDolphin / Fbtool — приём расходов (Keitaro Admin API)
Получайте расходы Facebook через API Dolphin (Fbtool) в реальном времени.
Читать гайд →ДокументацияЧистилка комментариев FB
Массовая модерация комментариев под рекламой Meta: скрывать, удалять и фильтровать по ключевым словам.
Читать гайд →ДокументацияИсточники трафика и партнёрские сети
Каталог 50+ источников трафика и 440+ сетей: шаблоны, параметры и адреса постбеков.
Читать гайд →ДокументацияОтчёты, логи и метрики
Конструктор отчётов, сохранённые отчёты, логи кликов и каждая метрика с пояснением.
Читать гайд →ДокументацияДомены и SSL
Добавление доменов, DNS, бесплатные сертификаты Let's Encrypt, редиректы, парковка и каждый переключатель на странице.
Читать гайд →ДокументацияCloudflare — DNS и SSL доменов
Как запускать домены кампаний через Cloudflare: DNS, режимы SSL и что отключить.
Читать гайд →ДокументацияАдминистрирование
Пользователи, роли и права, настройки безопасности, гео-базы, обновления и состояние системы.
Читать гайд →ДокументацияTelegram-бот
Управляйте трекером из Telegram: статистика, конверсии и алерты в чате.
Читать гайд →ДокументацияMCP-сервер: работа с трекером через нейросеть
Подключите Claude или любой MCP-клиент к Orbitra и управляйте кампаниями обычными словами.
Читать гайд →