Docs

PWA and Web Push

A PWA landing is a local landing that Orbitra renders into a full-blown web app: an "app store" storefront, a manifest and a service worker. Combined with the Web Push module it lets you grow a subscriber base right on the storefront and send them pushes β€” all by yourself, without external services (FCM is used only as the Android transport, Apple as the iOS transport; the keys and the database are yours).

This document covers: the PWA builder, app installation, domain binding, funnel instrumentation, the subscriber base, messages (manual and event-driven), the delivery cron and troubleshooting.


1. PWA landing: what it is and how it works

1.1 How it works inside

config_json contains "pwa": true. The click router, stream rotation and cloaking treat it like any other local landing β€” no new types.

index.html (a Google Play-style storefront), manifest.webmanifest and sw.js.

inside the manifest scope, so a root URL is not used.

storefront, so the push subscription, funnel beacons and the hop to the offer are attributed to the real click.

sheet (Android 94+ / desktop 105+): besides the base fields it declares id, lang, description (with the {value} macros resolved) and display_override, and lists every storefront screenshot that passes Chrome's sheet constraints (each side 320–3840px, side ratio ≀ 2.3) as screenshots with a narrow/wide form factor. The editor's Install readiness** card shows the same verdict live.

Firefox/Opera on Android see the browser-menu steps (iOS sees the Safari steps while ios_flow = instruction), and in-app webviews (Instagram, Facebook, TikTok, generic WebView) get a dismissible "open this page in your browser" card β€” the funnel underneath keeps running.

1.2 The builder

Landings β†’ Add PWA (or "Duplicate" on an existing one). The editor's main blocks:

BlockWhat it configures
GeneralApp name, slug, group, icon and screenshots (via the Content Gallery), category, developer, language, version, "updated"
StoreDescription (with {value} macros), tags, rating histogram, reviews, "what's new", badges (verified, glow, live counter), light/dark theme, color scheme
ScreenThe in-app screen shown after installation: type, title, text, button, image, custom HTML/JS
ActionsInstall-button action: to the offer / to a campaign / to a URL / nowhere (action_target), auto-redirect timers
PushEnable the push subscription on the app screen (push_enabled)
DomainDomain binding (see Β§2) + the offer for the direct domain
ReadinessA live checklist of what the native install sheet will look like: icon, description, screenshot sizes, push keys, domain binding

The Preview button renders the config draft with the production renderer β€” a live preview of the storefront and the screen (auto/iOS platform) without saving.

1.3 The funnel and beacons

The storefront page sends one-pixel beacons that write into the click:

standalone launch on iOS);

(at most once per 10 minutes per click);

subscription events;

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

All the columns are visible in click details β€” the main funnel diagnostics tool: the tracker names the reason itself, no browser logs needed.

1.4 The push subscription lives in the service worker

The subscription runs entirely inside the generated sw.js (orbitraSubscribe): the page merely sends a message to the worker and heads off to the offer. This is deliberate β€” on iOS the first, cold pushManager.subscribe can take tens of seconds, and the subscription must not depend on how long the user stays on the page. The worker also:

the push service's side, VAPID key update);

the tracker settings (self-heal) β€” reopening the app repairs the subscription without a reinstall;

(focusing an existing window and navigating to data.url).

The {vapid_public} placeholder in sw.js is substituted at file-serving time, not at generation β€” a VAPID key change reaches already installed apps without regenerating the static files.

1.5 RENDERER_VERSION

Every renderer change bumps RENDERER_VERSION (core/PwaLanding.php). On the next view of the landing the tracker compares the version marker in the rendered static files and regenerates outdated files by itself β€” no manual re-uploading to the server.


2. Domain β†’ PWA binding

A domain can be bound to a PWA directly: a visit to https://domain.com/ opens the storefront from the root, with no hop through a campaign and /lander/ β€” a clean install URL.

domains.

"Offer" button on the storefront still leads to the offer via /?_lp=1 with attribution.

binding; the binding beats index_campaign_id on the root.

real clicks into the archived system campaign orbitra-pwa-organic β€” it is created automatically and is not visible in the campaign list. Repeat visits with a live cookie do not spawn duplicates.


3. Web Push: the base, keys, sending

3.1 VAPID keys and the contact

The Push Base page (panel β†’ Push):

  1. Fill in the contact β€” mailto:[email protected] or https://…. Without

a real contact key generation is blocked: Apple (web.push.apple.com) validates the sub claim in the JWT and answers 403 BadJwtToken to placeholder addresses.

  1. Click Generate keys. The keys are stored in the tracker settings

(vapid_public_key / vapid_private_key / vapid_private_pem); encryption and signing are pure PHP + openssl (RFC 8291 + RFC 8292), no composer.

  1. Key rotation asks for confirmation: existing subscriptions stop being

valid, but every device quietly re-subscribes on the next opening of the app (self-heal); the base restores itself.

The diagnostics strip on the page shows: whether keys exist, the public key, the contact (with a warning if the default one is set), the age of the worker's last ping and the latest delivery error codes.

3.2 The "Subscribers" tab

The push_subscriptions table: id, click, endpoint, country, language, UA, status (active / expired), created, last shown. Capabilities:

the GDPR scenario);

and the cron**, instantly. Responses are decoded honestly: 403 β€” a hint about an invalid VAPID contact, 404/410 β€” the subscription is dead, anything else β€” the service's error code. This is the fastest way to test the whole pipe (keys β†’ JWT β†’ push service β†’ device).

Subscribers multiply through reinstalls and re-subscriptions (the endpoint is changed by the push service) β€” old rows expire by themselves via 404/410 on send, no separate cleanup needed. Before a blast, check a subscriber's "freshness" by its click (click details show the landing and the install UA).

3.3 The "Messages" tab

Messages are broadcast templates. Two kinds:

install (PWA install), lead, sale, delayed by delay_seconds seconds from the event.

Message fields: title (≀250), body (≀400), icon (a URL, conveniently from the Gallery), banner image (a URL β€” Android Chrome shows it as a large picture on the notification; iOS ignores it silently), click-through link, segment, country and language targeting, the "active" flag.

Segments are computed from the subscriber's conversion counters at the moment of queueing:

SegmentWho receives it
allall active subscribers
reg0no registration
reg1dep0registered, no deposit
reg1dep1registered and deposited

Targeting (migration 60) narrows any segment further at queue time: countries β€” a comma list of ISO codes matched against the subscriber's geo (US, DE), languages β€” 2-letter browser-language codes matched by primary subtag (en matches a subscriber stored as en-US). Empty list = no constraint. Junk entries are dropped on save, never stored.

The body supports macros expanded at send time: {variant1|variant2} (random choice, nesting ≀10), {Random=(X,Y)}, {subid} and other click macros β€” one message gives every recipient its own text.

3.3.1 Push clicks and the message CTR

Every notification the SW shows carries the delivery ids in its data (subid, message_id, sid). Tapping it fires one beacon (/pixel.gif?action=pwa&kind=pushclick) before the navigation, so the tap is counted even though the browser immediately leaves for the offer:

count per 10 minutes, like reopen counting) β€” this is the ROI number: subscribers β†’ clicks β†’ conversions, all on one funnel;

Push clicks per message with the click-through percentage;

3.3.2 Unsubscribing

The notification itself carries an Unsubscribe action button (localized, baked into the landing's SW; iOS ignores actions β€” tapping the notification there still opens). Pressing it POSTs the browser's endpoint to the public /push_unsubscribe ingest, which sets is_active = 0 (idempotent; the keys stay, so the panel can re-activate). There is also a standalone public page /push-unsubscribe?endpoint=<urlencoded> β€” it renders a confirm button (the deactivation is a POST behind it, so a prefetched link never unsubscribes anyone) and can be linked from anywhere.

The generated SW also serves a dedicated offline page for failed navigations (localized, with a Retry button) instead of the stale cached listing β€” a cached store page would beacon a stale click id and its CTA cannot work offline anyway.

3.4 Sending: the queue and the cron

The panel itself sends nothing. The "Send now" button on a message row queues (push_queue) one entry per active subscriber of the segment, with duplicate protection, and answers "Queued: N".

Delivery is done by the cron worker cli/push_cron.php β€” every minute:

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

The line is installed by install.sh automatically (marker # orbitra-push); check: crontab -u www-data -l | grep orbitra-push. The worker: flock against parallel runs, batches ≀300, retry after 300 seconds, 429 respects Retry-After, 401/403 β€” one retry with a fresh JWT, 404/410 β€” the subscription expires, 5xx/network β€” back into the queue. Event messages are triggered by the same worker via a cursor in settings.

Queue health is shown in the strip above the message list: pending/done/failed and the time of the worker's last ping. If the ping is not ticking β€” the cron is not installed or not running, and delivery will not happen.

3.5 What "sent" means

A 201 from the push service means "envelope accepted", not delivered. The push service cannot break the encryption (E2E): it answers 201 and silently drops the message if the device never reads it. The final judge is the phone alone. A monitored verification chain:

  1. Push Base β†’ Subscribers β†’ Send on the row β†’ the "accepted" banner;
  2. on the device: the notification shade (the banner may have silently passed while the

app was open);

  1. if 201 but silence β€” see Β§4.

4. Troubleshooting and common problems

No subscription at all β€” click details: push_fail_reason names the reason (unsupported = no Push API β€” the Telegram/Chrome webview on iOS; insecure = no HTTPS; nokey = VAPID not configured; denied = refused; timeout = slow network β€” the subscription will arrive on the next open via self-heal).

iOS β€” Safari only, and only from the home screen. Web push on iOS works under these conditions: iOS β‰₯ 16.4, the app added to the home screen specifically from Safari (plain Safari has no Notification object β€” a subscription is never created), a domain with a proper public certificate. An app added to the home screen from Chrome (CriOS) gets no push guarantee: check the installing browser by UA in click details (CriOS/… = Chrome, Version/… = Safari). If it does not work β€” reinstall the icon from Safari.

403 BadJwtToken when sending β€” an invalid VAPID contact: Apple rejects placeholder addresses (mailto:orbitra@localhost). Enter a real mailto:.

201 but not arriving for everyone everywhere β€” check that the server is on the latest version (git log --oneline -1 via sudo -u www-data): early builds had crypto-envelope defects (a header without keyid, a key schedule not per RFC 8291) that the service still accepted with a 201. Then a control experiment: desktop Chrome β†’ install the PWA β†’ Allow β†’ Send: if it arrives on the desktop but not on the iPhone β€” the problem is the device/channel (a VPN breaks the persistent APNs connection; Chrome installs); if the desktop gets nothing either β€” write to support with the error code from the diagnostics strip.

"Buttons don't click" after a panel update β€” almost always the browser cache with an old index.html: hard-reload (Cmd+Shift+R) or a private tab.

Silent cron β€” push_cron_last_ping_at is not ticking: the cron is not installed. crontab -u www-data -l | grep orbitra-push; the log is var/logs/push.log.


5. Tests

openssl, the key in k= matches the signed key, the record decrypts byte-for-byte the way the browser does it (keyid read off the wire), a reference vector from the web-push library (npm) decrypts with our code, HKDF per RFC 5869, record size limits (body ≀ 4096 bytes β€” the Apple/FCM limit).

pushclick pixel (throttle + push_sends.clicked_at), /push_unsubscribe and the public unsubscribe page, RBAC.

serve time, the Service-Worker-Allowed header.

organic clicks, binding priorities.

Leaving the in-app browser (renderer v19+)

A PWA cannot be installed inside the FB/IG/TikTok webview β€” every webview visit is a guaranteed funnel loss. With Auto-open in browser on (default), the landing leaves immediately: Android through an intent:// into Chrome (current URL as the fallback), iOS 17+ through x-safari-https://; older iOS keeps the instruction card. The escape URL carries the click id, and the external browser continues the same click β€” no second click, no split funnel. The PWA funnel card shows attempts and success rate (returns in a real browser). Only the money side ever escapes: a safe page keeps serving the safe content.

Delivery and conversion attribution

Offer macros in push text

{offer.value} / {offer.value1} / {offer.value2} resolve from the offer's per-country table (Country β†’ bonus / freespins / currency; empty country = universal fallback) by the subscriber's country, through the offer the subscription's click went to. The message editor has a live preview for a chosen country + offer. Without context the macro stays visible β€” never silently blank.

Sending at the subscriber's local time

The subscription stores the device's IANA timezone (older rows: derived from the geo country). A message with Send at subscriber's local time waits out the quiet hours β€” by default 23:00–08:00 local (push_quiet_hours) β€” and sends in the first allowed minute. The requeue keeps the row pending (last_code=quiet), it never fails.

Operator's own push notifications (panel PWA)

Everything above pushes to landing subscribers. The panel itself is also a PWA (installable from the browser), and Users & Profile β†’ Profile β†’ Push notifications lets the operator receive web push on their own devices β€” conversion alerts and day/week/month digests β€” no Telegram needed.

menu) β€” subtab Push to phone, personal for every user; the Telegram subtab (admin-only) holds the bot's chats and digest schedule. The Profile keeps a pointer card; the Push page carries a "these are landing subscribers" note pointing here.

the same /sw.js. When the browser offers installation, an Install pill appears in the navbar; iOS Safari is guided by the card's instructions (Share β†’ Add to Home Screen). Admins can generate the shared VAPID keys right in the card (contact included) β€” no detour to the Push page.

worker. The VAPID keypair is shared with the landing push base (Push page β†’ Subscribers β†’ keys) β€” one keypair, two audiences; no keys yet is the card's first hint. On iOS, notifications work only inside the installed app.

sale, deposit, … β€” and campaign IDs; empty = everything). Sent synchronously from the postback, like the Telegram alerts; a 404/410 endpoint retires the device automatically.

on Monday) and monthly (the last complete month, sent on the 1st) β€” clicks, conversions, revenue, profit β€” at the user's local digest_time. Windows are computed in the user's profile timezone (DST-safe) and compared against the UTC clicks.created_at; excluded safe-page hits are left out exactly as on the dashboard (orbitraSafePagePredicate). A missed Monday / 1st (cron down, digest just switched on) catches up on the next tick. Sent by cli/push_cron.php; the admin_push_digest_log sent-marker makes a double send impossible.

(migration 69) β€” kept strictly apart from push_subscriptions (those are landing visitors). API actions: admin_push_state, admin_push_subscribe, admin_push_unsubscribe, admin_push_settings_save, admin_push_test.

notificationclick (same-origin links only). Tests: php tests/admin_push_test.php.

Telegram weekly/monthly digests (migration 70)

The admin bot's daily summary grew two siblings, on the Notifications page β†’ Telegram: weekly (the last complete week, sent on Monday) and monthly (the last complete month, sent on the 1st); only the send time is configurable. All Telegram times β€” daily included β€” are read in the timezone of the first admin's profile, not server time. Per-chat toggles mirror the /weekly on|off and /monthly on|off bot commands; once-per-window delivery is locked by tg_digest_log (unique chat Γ— period Γ— window). Totals come from the same AdminPushNotify::digestWindow()/windowStats() helper the push digests use, so Telegram and push can never disagree on the numbers.

← Previous
Landing pages
Next β†’
PWA Funnel
View source on GitHub: github.com/fenjo26/Orbitra.link/wiki
All guides
Docs

Quick start: your first campaign

The short path: install the tracker, create a campaign, and get your first clicks and conversions in under an hour.

Read guide β†’
Docs

Installation and updates

Install Orbitra on a fresh Ubuntu or Debian server with one command, and update to new versions safely.

Read guide β†’
Docs

Migrating from Keitaro

Move campaigns, offers, sources and domains from Keitaro to Orbitra in one click β€” what transfers and what to check.

Read guide β†’
Docs

Migrating from Binom

Move campaigns and streams from Binom to Orbitra: what transfers automatically and what to set up by hand.

Read guide β†’
Docs

Feature overview

Everything Orbitra can do: campaigns and streams, cloaking, landings, PWA, postbacks, costs, reports and integrations.

Read guide β†’
Docs

Campaigns and streams

The complete reference: campaign settings, stream types, schemas, rotation, filters, test links and every option explained.

Read guide β†’
Docs

Cloaking

Full cloaking reference: detection layers, global settings, per-stream filters, verdicts and reports.

Read guide β†’
Docs

Browser check

How the JS check catches bots, VMs and emulators through contradictions in the browser environment.

Read guide β†’
Docs

Landing pages

Landing types, the {offer} macro, the JS adapter, LeadForge and multi-offer landings β€” the complete reference.

Read guide β†’
Docs

PWA and Web Push

Build installable PWA apps and collect push subscribers: settings, icons, events and notifications.

Read guide β†’
Docs

PWA Funnel

A multi-step PWA funnel: install prompts, event tracking and re-engagement notifications.

Read guide β†’
Docs

Conversion popups

Show real conversion events as on-page popups: setup, triggers and placement.

Read guide β†’
Docs

Session recordings and heatmaps

Replay real visits and see click and scroll maps. Storage limits and privacy notes.

Read guide β†’
Docs

Content gallery

Central storage for icons, screenshots and creatives used across PWAs and landings.

Read guide β†’
Docs

Creatives library

Store creatives with subid tracking and test them across campaigns.

Read guide β†’
Docs

External PWA and Telegram channels

Publish PWAs to external domains and run Telegram channels as a traffic source.

Read guide β†’
Docs

Postbacks and conversions

Incoming postbacks, conversion statuses and types, and outgoing S2S postbacks to your traffic source.

Read guide β†’
Docs

Costs

Import spend from Facebook, TikTok and Google Ads, or update it via API and cron β€” and how the revenue aggregator works.

Read guide β†’
Docs

Push and pop networks

Working with push and pop traffic sources: feeds, zone optimization and the zone killer.

Read guide β†’
Docs

Facebook / Meta

Cost import from Meta Ads and the Conversions API: server-side events with deduplication.

Read guide β†’
Docs

Dolphin / Fbtool

Receive Facebook costs through the Dolphin (Fbtool) API in real time.

Read guide β†’
Docs

FB comment cleaner

Bulk-moderate comments under Meta ads: hide, delete and filter by keywords.

Read guide β†’
Docs

Traffic sources and affiliate networks

Catalog of 50+ traffic sources and 440+ networks: templates, parameters and postback URLs.

Read guide β†’
Docs

Reports, logs and metrics

The report builder, saved reports, click logs and every metric explained.

Read guide β†’
Docs

Domains and SSL

Add domains, DNS, free Let's Encrypt certificates, redirects, parking and every switch on the page.

Read guide β†’
Docs

Cloudflare

How to run campaign domains through Cloudflare: DNS, SSL modes and what to turn off.

Read guide β†’
Docs

Administration

Users, roles and permissions, security settings, geo databases, updates and system health.

Read guide β†’
Docs

Telegram bot

Manage the tracker from Telegram: stats, conversions and alerts in chat.

Read guide β†’
Docs

MCP: an AI assistant in the tracker

Connect Claude or any MCP client to Orbitra and manage campaigns with plain-language commands.

Read guide β†’