9.4 KiB
Notifications push (runtime JumPHP) : spécification
Une application JumPHP qui tourne dans le navigateur peut envoyer des notifications sur le téléphone de ses utilisateurs, par
l'intermédiaire de l'application JumPHP runtime pour Android (apps/runtime-android). Apple : plus tard. Ce document est le
contrat commun entre :
- le runtime Android (
apps/runtime-android) : consentement, réception FCM, affichage, accusés ; - le serveur jumphp.net (dépôt
jumphp-playground) : abonnements, envoi, files, quotas, stats, studio, administration, MCP distant ; - l'extension moteur
jumphp/notification(extensions/notification, futur dépôtjumphp-notification) : l'API PHP des jeux / applis ; - les outils du développeur :
bin/jumphp notify ...(scripts) etbin/jumphp notify:mcp(serveur MCP local pour Claude).
Trois portes
- L'administrateur de jumphp.net : le droit
notifyde l'application est approuvé, commetcp/ssh(studio « Accès réseau », approbation par commit) ; il peut suspendre les notifications d'une application ou bloquer un appareil à tout moment. - Le propriétaire de l'application : seul lui détient le jeton d'envoi
jnt_…(créé dans le studio, montré une fois, révocable, stocké haché). Sans lui, rien ne part. - La personne : une boîte de dialogue native du runtime (« Titre veut vous envoyer des notifications. Autoriser ? ») ; son accord est gardé sur le téléphone, révocable application par application dans le runtime. Le runtime revérifie cet accord à chaque notification reçue (une notification d'une application non autorisée n'est jamais affichée et le serveur est prévenu).
Abonnement (page → runtime → serveur)
page (extension) runtime Android jumphp.net
│ ticket = POST /api/tcp/ticket {scope:"notify"} ─────────────────────────►│ (droit notify approuvé ?)
│ {"t":"notify-subscribe", ...} ──►│ vérifie origine + ticket (Ticket.kt)
│ │ dialogue natif (Autoriser / Refuser)
│ │ POST /api/notify/devices ─────────────►│ revérifie le ticket, enregistre
│◄── {"t":"notify-subscribed"} ────│◄──────────── {"subscription":"ns_…"} ──│
Messages page ↔ runtime (WebSocket ws://127.0.0.1:47820/v1, en plus de docs/runtime-protocol.md)
| Sens | Message |
|---|---|
| page → runtime | {"t":"notify-subscribe","app":"<slug>","title":"<titre>","ticket":"<ticket notify>","user":"<id choisi par le développeur, ≤128, optionnel>","groups":["<≤32 groupes de ≤64>"]} |
| runtime → page | {"t":"notify-subscribed","app":"<slug>","granted":true,"subscription":"ns_…"} ou `{"t":"notify-subscribed","app":"","granted":false,"reason":"denied |
| page → runtime | {"t":"notify-unsubscribe","app":"<slug>"} → {"t":"notify-unsubscribed","app":"<slug>"} |
| page → runtime | {"t":"notify-status","app":"<slug>"} → `{"t":"notify-status","app":"","granted":bool,"subscription":"ns_…" |
| runtime → page | hello gagne "notify":true quand le runtime sait afficher des notifications (Android) ; le runtime de bureau répond {"t":"error","code":"unsupported"} |
Le ticket notify est un ticket ordinaire de /api/tcp/ticket (même format, mêmes signatures) dont scope = notify et sans cible
(host / port vides). Refus gardé 10 min ; 30 s sans réponse = refus ; un seul dialogue à la fois (comme pair).
API du serveur (https://jumphp.net)
Côté runtime (identifié par l'appareil, jamais par la page) :
POST /api/notify/devices{device, secret, fcm, ticket, app, origin, user, groups, platform:"android", locale, runtime}→{subscription}.device= UUID généré par le runtime ;secret= 32 octets aléatoires base64url gardés par le runtime, jamais donnés aux pages ; le premier enregistrement d'undevicefixe le secret (stocké haché), les suivants doivent le redonner. Ré-abonnement = mise à jour (user, groups, fcm). Le jeton FCM change : même appel.DELETE /api/notify/devices/{subscription}{device, secret};DELETE /api/notify/devices{device, secret}= tout.POST /api/notify/ack{device, secret, events:[{n:"<id notification>", e:"delivered|opened|dismissed|refused", at}]}(par lots).
Côté développeur (Authorization: Bearer jnt_…, le jeton de l'application) :
POST /api/notify/send{to:{all?:true, users?:[], groups?:[], subscriptions?:[]}, title (≤65), body (≤240), url? (chemin de l'application, ex. "/play/?room=ABCD", ou une adresse de son origine), tag?, ttl? (s, défaut 86400, max 604800), data? (≤2 Ko JSON)}→{id:"nt_…", targets:N};dry_run:true= compte seulement.GET /api/notify/notifications?limit&before(historique) ;GET /api/notify/notifications/{id}(détail + compteurs).GET /api/notify/stats?from&to→ par jour :sent delivered opened dismissed refused failed, abonnés actifs, désabonnements.GET /api/notify/subscribers?user&group&limit&cursor(sans jeton FCM ni données d'appareil :subscription user groups created last_seen).GET /api/notify/groups;PUT /api/notify/users/{user}/groups{groups:[…]}(le développeur range ses utilisateurs côté serveur aussi).DELETE /api/notify/subscriptions/{subscription}(le développeur retire un abonné).
Erreurs JSON {error, code} ; 429 avec Retry-After. Quotas par défaut (modifiables par l'administrateur, par application) :
60 envois / minute, 20 000 livraisons / jour, 1 notification / 10 s vers une même personne pour un même tag.
Message FCM (data, priorité haute)
{"t":"notify","n":"nt_…","app":"<slug>","title":"…","body":"…","url":"https://…","tag":"…","sub":"ns_…","exp":"<unix>"} —
le runtime ne lit que ces clés. Le serveur réutilise App\Service\FcmSender (déjà là pour wake). Un jeton FCM refusé par Google =
abonnement marqué failed puis supprimé.
Notifications globales (administrateur)
L'administrateur peut envoyer à tous les appareils (ou ceux d'une application) une notification app:"jumphp" affichée sous le nom
JumPHP, dans un canal Android à part que la personne peut couper. Pas de jeton : la page d'administration et le MCP distant
(compte administrateur) seulement.
Runtime Android
- Dialogue de consentement (même mécanique que
pair:ConsentActivity), en 14 langues ; accord stocké par application (notify-grants), liste + révocation dans l'écran principal (révoquer =DELETEcôté serveur). FcmService:t:"notify"→ accord local présent et pas expiré ? → notification Android (un canal par application, nommé par son titre ;tagremplace la précédente) ; un clic ouvreurldans le navigateur et envoieopened; sinonrefused+ désabonnement.deliveredà l'affichage,dismissedau balayage. Accusés envoyés par lots (WorkManager / au prochain réveil).- Android 13+ : permission
POST_NOTIFICATIONSdemandée au premier abonnement. - Le journal (
Journal) note abonnements, révocations, notifications reçues (sans leur texte).
Extension jumphp/notification
$n = $this->engine->service(\JumphpExtensions\Notification\Notifications::class); // ou injecté dans la scène
$n->supported(); // navigateur + runtime Android prêt (sinon false, avec reason())
$n->subscribe(user: 'player-42', groups: ['beta'])->then(fn (bool $ok) => ...); // Task
$n->status()->then(fn (?Subscription $s) => ...);
$n->unsubscribe();
Gui : widget NotifyToggle (« Recevoir les notifications ») qui gère tout (runtime absent → RuntimeGuide). Côté serveur / scripts PHP :
JumphpExtensions\Notification\Sender (new Sender($token), send(), stats(), history(), groups(), setGroups()) qui
parle à l'API ci-dessus (Http du moteur, ou curl hors moteur).
Outils du développeur
bin/jumphp notify:login <app>: demande le jeton (saisie masquée), le garde dans~/.jumphp/notify/tokens.json(0600), jamais dans le dépôt.JUMPHP_NOTIFY_TOKEN/JUMPHP_NOTIFY_URLgagnent.bin/jumphp notify <app> --all|--user U|--group G "Titre" "Texte" [--url /play/] [--dry-run],notify:stats <app>,notify:history <app>.bin/jumphp notify:mcp: serveur MCP stdio (claude mcp add jumphp-notify -- bin/jumphp notify:mcp), outilsnotify_send,notify_dry_run,notify_stats,notify_history,notify_subscribers,notify_groups,notify_set_groups. Un envoi àalldemandeconfirm:true.- Le MCP distant de jumphp.net (
/mcp, jeton du compte) gagnenotify_send,notify_stats,notify_historypour les projets du compte.
Studio et administration (jumphp.net)
- Studio, projet → Notifications : activer (demande du droit
notify), créer / renouveler / révoquer le jeton, abonnés, groupes, formulaire d'envoi (aperçu, envoi test à soi), historique, statistiques (courbes par jour, taux d'ouverture). - Administration → Notifications : vue globale (applications, abonnés, envois du jour, échecs), statistiques complètes, quotas par application, suspendre une application, bloquer un appareil, notification globale, journal.
- Toutes les chaînes en 14 langues (
fr en es de it pt nl pl ru uk tr ja zh ko).