123 lines
9.4 KiB
Markdown
123 lines
9.4 KiB
Markdown
# 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ôt `jumphp-notification`) : l'API PHP des jeux / applis ;
|
|
- les **outils du développeur** : `bin/jumphp notify ...` (scripts) et `bin/jumphp notify:mcp` (serveur MCP local pour Claude).
|
|
|
|
## Trois portes
|
|
|
|
1. **L'administrateur de jumphp.net** : le droit `notify` de l'application est approuvé, comme `tcp` / `ssh` (studio « Accès réseau »,
|
|
approbation par commit) ; il peut suspendre les notifications d'une application ou bloquer un appareil à tout moment.
|
|
2. **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.
|
|
3. **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":"<slug>","granted":false,"reason":"denied|later|server|ticket"}` |
|
|
| page → runtime | `{"t":"notify-unsubscribe","app":"<slug>"}` → `{"t":"notify-unsubscribed","app":"<slug>"}` |
|
|
| page → runtime | `{"t":"notify-status","app":"<slug>"}` → `{"t":"notify-status","app":"<slug>","granted":bool,"subscription":"ns_…"|null,"user":"…"|null}` |
|
|
| 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'un `device` fixe 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 = `DELETE` côté serveur).
|
|
- `FcmService` : `t:"notify"` → accord local présent et pas expiré ? → notification Android (un canal par application, nommé par son titre ;
|
|
`tag` remplace la précédente) ; un clic ouvre `url` dans le navigateur et envoie `opened` ; sinon `refused` + désabonnement.
|
|
`delivered` à l'affichage, `dismissed` au balayage. Accusés envoyés par lots (WorkManager / au prochain réveil).
|
|
- Android 13+ : permission `POST_NOTIFICATIONS` demandée au premier abonnement.
|
|
- Le journal (`Journal`) note abonnements, révocations, notifications reçues (sans leur texte).
|
|
|
|
## Extension `jumphp/notification`
|
|
|
|
```php
|
|
$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_URL` gagnent.
|
|
- `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`), outils `notify_send`,
|
|
`notify_dry_run`, `notify_stats`, `notify_history`, `notify_subscribers`, `notify_groups`, `notify_set_groups`. Un envoi à `all`
|
|
demande `confirm:true`.
|
|
- Le MCP distant de jumphp.net (`/mcp`, jeton du compte) gagne `notify_send`, `notify_stats`, `notify_history` pour 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`).
|