Protocole embarqué UCP : handoff web et natif

Publiée le 8 septembre 2026 . Rattachée à le guide d'implémentation UCP.

Le protocole embarqué UCP permet d’afficher une interface marchande dans une plateforme web ou native tout en conservant un canal structuré. Il utilise JSON-RPC 2.0, un handshake explicite et une validation stricte de l’origine.

En bref

• Le web utilise postMessage, puis éventuellement MessageChannel.
• L’application native injecte une interface de messagerie dans sa WebView.
• Un échec de handshake impose l’arrêt de la session embarquée.

Quand utiliser le transport embarqué ?

Un checkout entièrement pilotable par API reste le chemin le plus direct. Le transport embarqué devient utile lorsqu’une étape doit rester dans l’interface du marchand : authentification, consentement, saisie réglementée ou interaction que l’API ne sait pas représenter.

Le continue_url relie les deux mondes. La plateforme l’ouvre dans une fenêtre, un iframe contrôlé ou une WebView. Le marchand conserve son interface, tandis que les deux parties échangent des messages structurés décrits par la spécification Embedded Protocol. Le cycle de vie du checkout reste la source d’état, et Identity Linking fournit l’identité quand la session embarquée réclame un jeton utilisateur.

Comment fonctionne le canal web ?

Au démarrage, l’hôte et le contexte embarqué communiquent avec window.postMessage(). L’hôte doit vérifier que l’origine du message correspond à celle du continue_url qui a ouvert la session. Une simple vérification du nom de message ne suffit pas.

L’hôte peut ensuite créer un MessageChannel et transférer un port dans la réponse ready. Si ce port est accepté, tous les messages suivants doivent utiliser ce canal. Sinon, les deux fenêtres continuent avec postMessage et valident l’origine à chaque échange.

Comment fonctionne une WebView native ?

L’application injecte une interface de consommation nommée selon la capacité. Pour le checkout, la forme préférée est window.EmbeddedCheckoutProtocolConsumer. Sur WebKit, une interface window.webkit.messageHandlers... peut être utilisée.

Le message transmis est une chaîne JSON représentant une requête JSON-RPC 2.0. L’hôte doit la parser avant traitement. Dans l’autre sens, l’application injecte un appel vers l’objet EmbeddedCheckoutProtocol ou son équivalent Cart.

Le handshake en quatre étapes

1. Le contexte embarqué envoie ready avec les délégations demandées et, si besoin, une demande d’authentification.
2. L’hôte confirme la version UCP et les délégations acceptées.
3. S’il propose un MessagePort, le contexte change de canal et renvoie ready.
4. Si la réponse contient error_response, l’hôte détruit le contexte et peut rediriger vers le continue_url prévu.

Après une erreur de handshake, le contexte embarqué ne doit plus envoyer de message. Ce point empêche une interface partiellement initialisée de continuer à modifier la session.

États, délégation et authentification

La délégation précise qui contrôle une partie de l’expérience. Une interface marchande peut par exemple gérer une étape pendant que l’hôte conserve l’enveloppe du checkout. Les changements d’état restent transmis par messages, afin que l’hôte ne déduise pas la réussite depuis un événement visuel.

Le contexte peut demander un nouveau credential après le handshake, notamment si un jeton OAuth expire. Le credential voyage dans une réponse JSON-RPC dédiée. Il ne doit être ni écrit dans l’URL ni journalisé.

Erreurs à tester

Code	Sens	Réaction
abort_error	utilisateur parti	fermer proprement, reprise possible
security_error	origine invalide	arrêter sans nouvelle communication
invalid_state_error	ordre de messages incorrect	détruire la session
not_supported_error	opération inconnue	proposer un autre parcours
timeout_error	délai interne	reprise contrôlée possible

Checklist d’intégration

• dériver l’origine autorisée du continue_url validé ;
• utiliser des IDs JSON-RPC uniques ;
• empêcher tout message avant ready ;
• basculer entièrement vers MessagePort après l’upgrade ;
• détruire le contexte après un handshake en erreur ;
• masquer les credentials dans la télémétrie ;
• synchroniser l’état via le protocole, jamais par lecture du DOM embarqué.

Sources

• UCP, Embedded Protocol
• UCP, Checkout Capability
• MDN, Window.postMessage

---

Revenir à le guide d'implémentation UCP · Toutes les notes · Read in English