Docs

PWA et Web Push

Une landing PWA est une landing locale qu'Orbitra rend comme une véritable web app : une vitrine façon « app store », un manifest et un service worker. Combinée au module Web Push, elle vous permet de faire grandir une base d'abonnés directement sur la vitrine et de leur envoyer des push — tout par vous-même, sans services externes (FCM ne sert que de transport Android, Apple de transport iOS ; les clés et la base de données sont les vôtres).

Ce document couvre : le constructeur PWA, l'installation de l'app, la liaison de domaine, l'instrumentation du funnel, la base d'abonnés, les messages (manuels et pilotés par événement), le cron de livraison et le dépannage.


1. Landing PWA : c'est quoi et comment ça marche

1.1 Comment ça marche à l'intérieur

config_json contient "pwa": true. Le routeur de clics, la rotation des streams et le cloaking la traitent comme n'importe quelle autre landing locale — aucun nouveau type.

index.html (une vitrine façon Google Play), manifest.webmanifest et sw.js.

qu'à l'intérieur du scope du manifest, donc une URL racine n'est pas utilisée.

vitrine, pour que la souscription push, les beacons du funnel et le saut vers l'offre soient attribués au vrai clic.

riche de Chrome (Android 94+ / desktop 105+) : outre les champs de base, il déclare id, lang, description (avec les macros {value} résolues) et display_override, et liste chaque capture d'écran de la vitrine qui passe les contraintes de la fiche de Chrome (chaque côté 320–3840px, ratio de côté ≤ 2.3) comme screenshots avec un facteur de forme narrow/wide. La carte Install readiness** de l'éditeur montre le même verdict en direct.

Firefox/Opera sur Android voient les étapes du menu du navigateur (iOS voit les étapes Safari tant que ios_flow = instruction), et les webviews in-app (Instagram, Facebook, TikTok, WebView générique) reçoivent une carte « open this page in your browser » dismissible — le funnel en dessous continue de tourner.

1.2 Le constructeur

Landings → Add PWA (ou « Duplicate » sur une existante). Les blocs principaux de l'éditeur :

BlocCe qu'il configure
GeneralNom de l'app, slug, groupe, icône et captures d'écran (via la Content Gallery), catégorie, développeur, langue, version, « updated »
StoreDescription (avec macros {value}), tags, histogramme de notes, avis, « what's new », badges (verified, glow, compteur live), thème light/dark, schéma de couleurs
ScreenL'écran in-app montré après l'installation : type, titre, texte, bouton, image, HTML/JS personnalisé
ActionsAction du bouton d'installation : vers l'offre / vers une campagne / vers une URL / nulle part (action_target), timers d'auto-redirection
PushActiver la souscription push sur l'écran de l'app (push_enabled)
DomainLiaison de domaine (voir §2) + l'offre pour le domaine direct
ReadinessUne checklist en direct de ce à quoi ressemblera la fiche d'installation native : icône, description, tailles des captures, clés push, liaison de domaine

Le bouton Preview rend le brouillon de config avec le renderer de production — une preview en direct de la vitrine et de l'écran (plateforme auto/iOS) sans enregistrer.

1.3 Le funnel et les beacons

La page de la vitrine envoie des beacons d'un pixel qui écrivent dans le clic :

lancement standalone sur iOS) ;

(au plus une fois par 10 minutes par clic) ;

souscription push ;

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

Toutes les colonnes sont visibles dans les détails de clic — l'outil principal de diagnostic du funnel : le tracker nomme lui-même la raison, pas besoin de logs navigateur.

1.4 La souscription push vit dans le service worker

La souscription tourne entièrement dans le sw.js généré (orbitraSubscribe) : la page se contente d'envoyer un message au worker et part vers l'offre. C'est délibéré — sur iOS le premier pushManager.subscribe à froid peut prendre des dizaines de secondes, et la souscription ne doit pas dépendre de la durée du séjour de l'utilisateur sur la page. Le worker aussi :

côté service push, mise à jour de la clé VAPID) ;

les réglages du tracker (self-heal) — rouvrir l'app répare la souscription sans réinstallation ;

(en se focalisant sur une fenêtre existante et en naviguant vers data.url).

Le placeholder {vapid_public} dans sw.js est substitué au moment de servir le fichier, pas à la génération — un changement de clé VAPID atteint les apps déjà installées sans regénérer les fichiers statiques.

1.5 RENDERER_VERSION

Chaque changement de renderer incrémente RENDERER_VERSION (core/PwaLanding.php). À la prochaine vue de la landing, le tracker compare le marqueur de version dans les fichiers statiques rendus et regénère lui-même les fichiers périmés — pas de re-téléversement manuel vers le serveur.


2. Liaison Domaine → PWA

Un domaine peut être lié à une PWA directement : une visite de https://domain.com/ ouvre la vitrine depuis la racine, sans saut par une campagne ni par /lander/ — une URL d'installation propre.

domaines.

bouton « Offer » de la vitrine mène toujours à l'offre via /?_lp=1 avec attribution.

liaison ; la liaison bat index_campaign_id sur la racine.

de vrais clics dans la campagne système archivée orbitra-pwa-organic — elle est créée automatiquement et n'est pas visible dans la liste des campagnes. Les visites répétées avec un cookie vivant ne produisent pas de doublons.


3. Web Push : la base, les clés, l'envoi

3.1 Clés VAPID et le contact

La page Push Base (panneau → Push) :

  1. Remplissez le contact — mailto:[email protected] ou https://…. Sans

un vrai contact, la génération de clés est bloquée : Apple (web.push.apple.com) valide la claim sub du JWT et répond 403 BadJwtToken aux adresses placeholder.

  1. Cliquez sur Generate keys. Les clés sont stockées dans les réglages du tracker

(vapid_public_key / vapid_private_key / vapid_private_pem) ; le chiffrement et la signature sont en pur PHP + openssl (RFC 8291 + RFC 8292), pas de composer.

  1. La rotation des clés demande une confirmation : les souscriptions existantes cessent d'être

valides, mais chaque appareil se re-souscrit discrètement à la prochaine ouverture de l'app (self-heal) ; la base se restaure seule.

La bande de diagnostics de la page montre : si les clés existent, la clé publique, le contact (avec un avertissement si celui par défaut est réglé), l'âge du dernier ping du worker et les derniers codes d'erreur de livraison.

3.2 L'onglet « Subscribers »

La table push_subscriptions : id, clic, endpoint, pays, langue, UA, statut (active / expired), créé, dernière présentation. Capacités :

le scénario RGPD) ;

et le cron**, instantanément. Les réponses sont décodées honnêtement : 403 — un indice sur un contact VAPID invalide, 404/410 — la souscription est morte, tout le reste — le code d'erreur du service. C'est le moyen le plus rapide de tester toute la tuyauterie (clés → JWT → service push → appareil).

Les abonnés se multiplient à travers réinstallations et re-souscriptions (l'endpoint est changé par le service push) — les vieilles lignes expirent d'elles-mêmes via 404/410 à l'envoi, pas de nettoyage séparé nécessaire. Avant un blast, vérifiez la « fraîcheur » d'un abonné par son clic (les détails de clic montrent la landing et l'UA d'installation).

3.3 L'onglet « Messages »

Les messages sont des templates de diffusion. Deux sortes :

install (installation PWA), lead, sale, retardés de delay_seconds secondes depuis l'événement.

Champs du message : titre (≤250), corps (≤400), icône (une URL, idéalement depuis la Gallery), image de bannière (une URL — Chrome Android la montre comme une grande image sur la notification ; iOS l'ignore silencieusement), lien de clic, segment, ciblage pays et langue, le flag « active ».

Les segments sont calculés depuis les compteurs de conversion de l'abonné au moment de la mise en file :

SegmentQui le reçoit
alltous les abonnés actifs
reg0aucune inscription
reg1dep0inscrit, aucun dépôt
reg1dep1inscrit et a déposé

Le ciblage (migration 60) resserre n'importe quel segment au moment de la mise en file : countries — une liste d'ISO séparés par des virgules comparée au geo de l'abonné (US, DE), languages — codes de langue navigateur à 2 lettres comparés par sous-tag primaire (en correspond à un abonné stocké en en-US). Liste vide = aucune contrainte. Les entrées indésirables sont éliminées à l'enregistrement, jamais stockées.

Le corps supporte les macros étendues au moment de l'envoi : {variant1|variant2} (choix aléatoire, nesting ≤10), {Random=(X,Y)}, {subid} et les autres macros de clic — un message donne à chaque destinataire son propre texte.

3.3.1 Clics push et CTR du message

Chaque notification que le SW montre porte les ids de livraison dans son data (subid, message_id, sid). La toucher déclenche un beacon (/pixel.gif?action=pwa&kind=pushclick) avant la navigation, pour que le tap soit compté même si le navigateur part aussitôt vers l'offre :

comptage par 10 minutes, comme le comptage des réouvertures) — c'est le chiffre du ROI : abonnés → clics → conversions, tout sur un seul funnel ;

Push clicks par message avec le pourcentage de clic ;

3.3.2 Se désabonner

La notification elle-même porte un bouton d'action Unsubscribe (localisé, cuit dans le SW de la landing ; iOS ignore les actions — toucher la notification là-bas ouvre quand même). Le presser POSTe l'endpoint du navigateur vers l'ingest public /push_unsubscribe, qui met is_active = 0 (idempotent ; les clés restent, donc le panneau peut réactiver). Il y a aussi une page publique autonome /push-unsubscribe?endpoint=<urlencoded> — elle rend un bouton de confirmation (la désactivation est un POST derrière, donc un lien prefetché ne désabonne jamais personne) et peut être liée de n'importe où.

Le SW généré sert aussi une page offline dédiée pour les navigations ratées (localisée, avec un bouton Retry) au lieu du listing en cache périmé — une page store en cache beaconerait un id de clic périmé et son CTA ne peut de toute façon pas marcher hors ligne.

3.4 L'envoi : la file et le cron

Le panneau lui-même n'envoie rien. Le bouton « Send now » sur une ligne de message met en file (push_queue) une entrée par abonné actif du segment, avec protection anti-doublons, et répond « Queued: N ».

La livraison est faite par le worker cron cli/push_cron.php — chaque minute :

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

La ligne est installée par install.sh automatiquement (marqueur # orbitra-push) ; vérifiez : crontab -u www-data -l | grep orbitra-push. Le worker : flock contre les exécutions parallèles, batches ≤300, retry après 300 secondes, 429 respecte Retry-After, 401/403 — un retry avec un JWT frais, 404/410 — la souscription expire, 5xx/réseau — retour dans la file. Les messages événementiels sont déclenchés par le même worker via un curseur dans les réglages.

La santé de la file est montrée dans la bande au-dessus de la liste des messages : pending/done/failed et l'heure du dernier ping du worker. Si le ping ne tourne plus — le cron n'est pas installé ou ne tourne pas, et la livraison n'aura pas lieu.

3.5 Ce que « envoyé » veut dire

Un 201 du service push signifie « enveloppe acceptée », pas « livré ». Le service push ne peut pas casser le chiffrement (E2E) : il répond 201 et jette silencieusement le message si l'appareil ne le lit jamais. Le juge final, c'est le téléphone seul. Une chaîne de vérification outillée :

  1. Push Base → Subscribers → Send sur la ligne → la bannière « accepted » ;
  2. sur l'appareil : le volet de notifications (la bannière a pu passer silencieusement pendant que

l'app était ouverte) ;

  1. si 201 mais silence — voir §4.

4. Dépannage et problèmes courants

Aucune souscription du tout — détails de clic : push_fail_reason nomme la raison (unsupported = pas de Push API — le webview Telegram/Chrome sur iOS ; insecure = pas de HTTPS ; nokey = VAPID non configuré ; denied = refusé ; timeout = réseau lent — la souscription arrivera à la prochaine ouverture via le self-heal).

iOS — Safari seulement, et seulement depuis l'écran d'accueil. Le web push sur iOS marche sous ces conditions : iOS ≥ 16.4, l'app ajoutée à l'écran d'accueil spécifiquement depuis Safari (le Safari nu n'a pas d'objet Notification — une souscription n'est jamais créée), un domaine avec un vrai certificat public. Une app ajoutée à l'écran d'accueil depuis Chrome (CriOS) n'a aucune garantie de push : vérifiez le navigateur d'installation par l'UA dans les détails de clic (CriOS/… = Chrome, Version/… = Safari). Si ça ne marche pas — réinstallez l'icône depuis Safari.

403 BadJwtToken à l'envoi — un contact VAPID invalide : Apple rejette les adresses placeholder (mailto:orbitra@localhost). Saisissez un vrai mailto:.

201 mais rien n'arrive pour tout le monde partout — vérifiez que le serveur est sur la dernière version (git log --oneline -1 via sudo -u www-data) : les builds primitifs avaient des défauts d'enveloppe crypto (un en-tête sans keyid, un key schedule non conforme à la RFC 8291) que le service acceptait quand même avec un 201. Puis une expérience contrôle : Chrome desktop → installez la PWA → Allow → Send : si ça arrive sur le desktop mais pas sur l' iPhone — le problème est l'appareil/le canal (un VPN casse la connexion persistante APNs ; Chrome s'installe) ; si le desktop ne reçoit rien non plus — écrivez au support avec le code d'erreur de la bande de diagnostics.

« Les boutons ne cliquent pas » après une mise à jour du panneau — presque toujours le cache navigateur avec un vieux index.html : hard-reload (Cmd+Shift+R) ou un onglet privé.

Cron silencieux — push_cron_last_ping_at ne tourne plus : le cron n'est pas installé. crontab -u www-data -l | grep orbitra-push ; le log est var/logs/push.log.


5. Tests

openssl, la clé dans k= correspond à la clé signée, l'enregistrement se déchiffre octet par octet comme le navigateur le fait (keyid lu sur le fil), un vecteur de référence de la librairie web-push (npm) se déchiffre avec notre code, HKDF selon la RFC 5869, limites de taille d'enregistrement (corps ≤ 4096 octets — la limite Apple/FCM).

pixel pushclick (throttle + push_sends.clicked_at), /push_unsubscribe et la page publique de désabonnement, RBAC.

moment de servir, l'en-tête Service-Worker-Allowed.

clics organiques, priorités de liaison.

Quitter l'in-app browser (renderer v19+)

Une PWA ne peut pas s'installer dans le webview FB/IG/TikTok — chaque visite en webview est une perte de funnel garantie. Avec Auto-open in browser activé (le défaut), la landing part aussitôt : Android via un intent:// vers Chrome (l'URL courante en fallback), iOS 17+ via x-safari-https:// ; l'iOS plus ancien garde la carte d'instructions. L'URL d'évasion porte l'id de clic, et le navigateur externe continue le même clic — pas de second clic, pas de funnel scindé. La carte du funnel PWA montre les tentatives et le taux de succès (retours dans un vrai navigateur). Seul le côté money s'échappe jamais : une page safe continue de servir le contenu safe.

Livraison et attribution de conversion

Macros d'offre dans le texte des push

{offer.value} / {offer.value1} / {offer.value2} se résolvent depuis la table par pays de l'offre (Country → bonus / freespins / devise ; pays vide = fallback universel) selon le pays de l'abonné, à travers l'offre vers laquelle le clic de la souscription est allé. L'éditeur de message a une preview en direct pour un pays + offre choisis. Sans contexte, la macro reste visible — jamais blankée en silence.

Envoi à l'heure locale de l'abonné

La souscription stocke le fuseau IANA de l'appareil (lignes plus anciennes : dérivé du pays geo). Un message avec Send at subscriber's local time attend la fin des heures creuses — par défaut 23:00–08:00 locales (push_quiet_hours) — et envoie à la première minute permise. La remise en file garde la ligne pending (last_code=quiet), elle n'échoue jamais.

Les push de l'opérateur lui-même (PWA du panneau)

Tout ce qui précède pousse vers les abonnés des landings. Le panneau lui-même est aussi une PWA (installable depuis le navigateur), et Users & Profile → Profile → Push notifications permet à l'opérateur de recevoir du web push sur ses propres appareils — alertes de conversion et digests jour/semaine/mois — sans Telegram.

engrenage) — sous-onglet Push to phone, personnel pour chaque utilisateur ; le sous-onglet Telegram (admin seulement) contient les chats du bot et le planning des digests. Le Profile garde une carte de renvoi ; la page Push porte une note « ce sont les abonnés des landings » pointant vers ici.

le même /sw.js. Quand le navigateur propose l'installation, une pill Install apparaît dans la navbar ; iOS Safari est guidé par les instructions de la carte (Share → Add to Home Screen). Les admins peuvent générer les clés VAPID partagées directement dans la carte (contact compris) — pas de détour par la page Push.

Push → Subscribers → clés) — un keypair, deux audiences ; pas encore de clés est le premier indice de la carte. Sur iOS, les notifications marchent seulement dans l'app installée.

sale, deposit, … — et IDs de campagnes ; vide = tout). Envoyé synchroniquement depuis le postback, comme les alertes Telegram ; un endpoint 404/410 retire l'appareil automatiquement.

le lundi) et mensuel (le dernier mois complet, envoyé le 1er) — clics, conversions, revenue, profit — à l'heure locale digest_time de l'utilisateur. Les fenêtres sont calculées dans le fuseau du profil de l'utilisateur (DST-safe) et comparées au clicks.created_at UTC ; les visites de page safe exclues sont laissées de côté exactement comme sur le dashboard (orbitraSafePagePredicate). Un lundi / 1er manqué (cron en panne, digest tout juste activé) se rattrape au tick suivant. Envoyé par cli/push_cron.php ; le marqueur d'envoi admin_push_digest_log rend un double envoi impossible.

(migration 69) — tenues strictement à part de push_subscriptions (celles-là sont des visiteurs de landings). Actions API : admin_push_state, admin_push_subscribe, admin_push_unsubscribe, admin_push_settings_save, admin_push_test.

notificationclick (liens same-origin seulement). Tests : php tests/admin_push_test.php.

Digests Telegram hebdo/mensuels (migration 70)

Le résumé quotidien du bot admin s'est vu adjoindre deux variantes, sur la page Notifications → Telegram : hebdo (la dernière semaine complète, envoyée le lundi) et mensuel (le dernier mois complet, envoyé le 1er) ; seul le moment d'envoi est configurable. Toutes les heures Telegram — le quotidien compris — sont lues dans le fuseau du profil du premier admin, pas dans l'heure du serveur. Les toggles par chat miroitent les commandes du bot /weekly on|off et /monthly on|off ; une livraison par fenêtre est verrouillée par tg_digest_log (unique chat × période × fenêtre). Les totaux viennent du même helper AdminPushNotify::digestWindow()/windowStats() que les digests push utilisent, pour que Telegram et push ne puissent jamais se contredire sur les chiffres.

← Précédent
Landing pages
Suivant →
Funnel de visite PWA
Voir la source sur GitHub: github.com/fenjo26/Orbitra.link/wiki
Tous les guides
Docs

Démarrage rapide : votre première campagne

Le chemin court : installez le tracker, créez une campagne et obtenez vos premiers clics et conversions en moins d'une heure.

Lire le guide →
Docs

Installation et mises à jour

Installez Orbitra sur un serveur Ubuntu ou Debian tout neuf en une commande, et passez aux nouvelles versions sans risque.

Lire le guide →
Docs

Migrer depuis Keitaro

Déplacez campagnes, offres, sources et domaines de Keitaro vers Orbitra : ce qui est transféré et quoi vérifier après l'import.

Lire le guide →
Docs

Migrer depuis Binom

Déplacez campagnes et streams de Binom vers Orbitra via l'API publique v2 : ce qui est transféré automatiquement et quoi régler à la main.

Lire le guide →
Docs

Aperçu des fonctionnalités

Tout ce qu'Orbitra sait faire : campaigns et streams, cloaking, landings, PWA, postbacks, coûts, rapports et intégrations.

Lire le guide →
Docs

Campaigns et streams

La référence complète : réglages de campagne, types de streams, schémas, rotation, filtres, test links et chaque option expliquée.

Lire le guide →
Docs

Cloaking

La référence complète du cloaking : couches de détection, réglages globaux, filtres par stream, verdicts et rapports.

Lire le guide →
Docs

Browser check

Comment la vérification JS attrape bots, VM et émulateurs à travers les contradictions de l'environnement du navigateur.

Lire le guide →
Docs

Landing pages

Types de landings, la macro {offer}, l'adaptateur JS, LeadForge et les landings multi-offres — la référence complète.

Lire le guide →
Docs

PWA et Web Push

Construisez des apps PWA installables et collectez des abonnés push : réglages, icônes, événements et notifications.

Lire le guide →
Docs

Funnel de visite PWA

Le funnel configurable des landings PWA : étapes ordonnées, store, instructions et carte push, tracking par écran, statistiques de transitions et éditeur.

Lire le guide →
Docs

Popups de conversion

Un popup avec bouton d'offre sur vos landings : templates par vertical, déclencheurs, designs, une vraie étape du funnel et les métriques Popup CTR.

Lire le guide →
Docs

Enregistrements de session

Replay des visites façon vidéo, heatmap de clics et carte de scroll : activation, sites entiers, consentement cookies, stockage et dépannage.

Lire le guide →
Docs

Content Gallery : référence complète

La médiathèque partagée du tracker : dossiers, uploads, limites de formats, MediaPicker et contrat de taille dans les éditeurs PWA, landing et offre.

Lire le guide →
Docs

Bibliothèque de créas

L'onglet Creatives de la galerie : sync Facebook/TikTok, dépense et ROI par créa, rattachement des brouillons, alertes burnout et rapports.

Lire le guide →
Docs

PWA externes et chaînes Telegram

Builders PWA tiers comme cibles de stream avec installs et postbacks attribués, et offres chaîne Telegram via funnel bots avec conversions tg_join.

Lire le guide →
Docs

Postbacks et conversions

Postbacks entrants, types de conversion et devises, postbacks S2S sortants, macros, file de livraison, testeur, import et Conversions API.

Lire le guide →
Docs

Coûts : import de la dépense

Import de la dépense Facebook, TikTok, Google Ads et réseaux push/pop : matching par IDs, diagnostics, agences, métriques plateforme et agrégateur de revenus.

Lire le guide →
Docs

Réseaux push et pop

Import de dépense AdMaven, PropellerAds, Kadam et autres, et le Zone Killer : règles dry-run/auto pour bloquer les zones qui brûlent de l'argent.

Lire le guide →
Docs

Facebook / Meta

Les deux intégrations Facebook : import de coûts avec mapping des paramètres, et Conversions API avec matching navigateur, consentement et dépannage.

Lire le guide →
Docs

Dolphin / Fbtool

Recevoir les coûts Facebook de Dolphin et Fbtool.pro sur l'endpoint compatible Keitaro : clé API, matching par adset/ad et répartition de la dépense sur les clics.

Lire le guide →
Docs

Nettoyage des commentaires FB

Modération planifiée des commentaires spam sous vos pubs Facebook : dry-run, stop words, regexes admin, whitelist, journal et restauration en un clic.

Lire le guide →
Docs

Sources de trafic et réseaux d'affiliation

Les deux annuaires du funnel : templates de sources avec paramètres et macros, postback vers la source, réseaux d'affiliation et paramètres d'offre.

Lire le guide →
Docs

Rapports, logs et métriques

Dashboard, liste des campagnes, rapport à dimensions, tendances et cohortes, journal du trafic, carte du clic et le détail du calcul de chaque métrique.

Lire le guide →
Docs

Domaines et SSL

Ajouter des domaines, réglages par domaine, certificats Let's Encrypt et Cloudflare, registrars connectés et surveillance Backorder.

Lire le guide →
Docs

Cloudflare

Connecter Cloudflare via l'API : parking DNS automatique, proxy orange, modes SSL de zone, import des zones et réécriture des enregistrements A.

Lire le guide →
Docs

Administration

Utilisateurs, rôles et permissions, clés API, réglages du tracker, bases geo, mises à jour et menu ⚙ : archive, statuts, logs et extension Ads Manager.

Lire le guide →
Docs

Bot Telegram

Statistiques, conversions et digest quotidien dans Telegram : connexion par token, webhook ou polling, commandes, notifications et alertes vers les chaînes.

Lire le guide →
Docs

MCP : un assistant IA dans le tracker

Connecter Claude Desktop ou tout client MCP à Orbitra via le serveur MCP : clés API, options de connexion et les 41 tools disponibles.

Lire le guide →