Appearance
Transports : choisir le bon contrat
Le SDK app tourne dans l'iframe enfant. Le SDK overlay est le parent qui l'héberge. Les pages plugins viewers et streamer/admin sont d'autres documents, équipés du helper KappappsHost. Une Promise n'a pas la même signification sur tous ces chemins.
| Besoin | API / trajet | Ce que la réussite établit |
|---|---|---|
| Observer un service dans cette exécution | service.events.on/once/off | Callback local ; pas un envoi réseau. Voir events. |
| Lire/écrire une ressource plateforme | Service SDK dédié → HTTP | Réponse de l'endpoint, selon son contrat ; pas une transaction commune avec les autres appels. |
| Afficher, masquer ou terminer l'iframe | display, undisplay, finish, abort → MessagePort vers le parent | Signal de cycle de vie ; voir ses étapes et erreurs. |
| Page plugin → appli active | Helper → HTTP Kappapps → Core → overlay parent → SDK app | emit confirme la prise en charge du transport, sans preuve de traitement métier. |
| Appli → pages plugins | kapp.plugin.emitViewers/emitStreamer → HTTP → relais temps réel → hôte de page → helper | Acceptation du relais, sans preuve qu'une page est ouverte ou a reçu le message. |
| Attendre une décision de l'appli depuis un plugin | emitWithReply + reply explicite | Objet JSON choisi par le gestionnaire ; sa signification dépend du moment où il répond. Voir protocole. |
| Appeler une fonction d'une appli déjà lancée | kapp.services.call | Réponse du service ; ne lance pas une nouvelle partie. Voir services. |
| Lancer une cible et attendre sa fin | kapp.apps.run/runApp/runWidget | Résultat structuré de fin ou motif d'échec ; voir app-to-app. |
HTTP, attente différée et fermeture
Les services SDK passent par kapp.api. Réutilise leurs méthodes publiques : ne construis pas des routes internes, des sockets supplémentaires ou des messages du protocole parent pour contourner leurs contrats.
Dans le SDK V2 actuel, la file HTTP d'une exécution a 3 requêtes concurrentes et 100 départs par minute. Ce réglage local ne représente ni le quota serveur ni une capacité viewers garantie. Une attente différée peut conserver une place dans cette file. Une requête HTTP dure au plus 30 s ; l'attente totale générique (file, HTTP, éventuelle réponse différée) est bornée à 30 minutes. Les lanceurs kapp.apps utilisent leur propre budget total, 120 s par défaut.
Ces valeurs diffèrent de celles du helper plugin. Ne déduis pas un délai global du timeout HTTP d'une seule étape. La fermeture libère les attentes locales et interrompt les XHR ; elle ne revient pas sur les actions déjà exécutées par un serveur.
Les erreurs SDK ne sont pas nécessairement des instances de Error : elles peuvent être des objets {status, reason, ...}. Les attentes locales expirées utilisent notamment status: 0, reason: 'timeout', et celles annulées à la sortie reason: 'app-ended'. Les erreurs de relais plugins ajoutent code ; voir leur contrat. Le helper V3 normalise ses rejets en KappappsHostError. Les lanceurs kapp.apps résolvent un objet {resolved, data?, reason?} : lire resolved, pas seulement attendre la Promise.
Réception, doublons et incertitude
Aucun de ces transports ne fournit à lui seul une garantie métier « exactement une fois ». Après un timeout, le destinataire peut avoir reçu la demande, exécuté l'action puis perdu sa réponse. N'interprète pas un timeout comme une autorisation de recommencer un achat, une récompense ou un lancement.
Les messages temps réel ne constituent pas un journal durable. Prévois un instantané récupérable pour une page arrivée tard ou revenue après une coupure. L'ordre des appels JavaScript ne garantit pas l'ordre de leur traitement distant : plusieurs requêtes et plusieurs onglets peuvent agir simultanément. Le helper dispose d'une file, pas d'une transaction sur les actions métier.
Pour diagnostiquer, distingue initialisation locale, réponse HTTP, réception par un gestionnaire, effet métier et confirmation. Journalise un identifiant d'exécution/action et un résultat synthétique sans token ni payload privé. Valide dans le shell DEV HUB réel, puis teste séparément arrivée tardive, doublon, arrêt et perte de réponse. Les tests locaux du SDK ne prouvent pas la disponibilité du Core ou des relais effectivement déployés.