Contribuer une action de parcours utilisateur

Déclarer le runtime

Le package annonce son entrypoint navigateur dans extension.yaml :

spec:
  runtime:
    api: ./api/index.cjs
    journey: ./journey/index.js

Déclarer ce runtime n’autorise aucun chargement anticipé. Installer l’extension, utiliser un de ses nodes ailleurs dans le processus ou ouvrir un parcours qui n’affiche pas son action ne doit pas télécharger ni exécuter son code navigateur.

Contrat des actions

Le runtime expose un registre journeyActions. Chaque clé utilise exactement le namespace de l’extension et la forme <extension_key>.<action_key>.

export default {
  extension: { key: 'acme_pay', configSchema: { fields: [] } },
  journeyActions: {
    'acme_pay.collect_payment': {
      Component: AcmePayment,
      i18n_namespace: 'plugin.acme_pay',
      hideSubmit: true,
      validate: () => null,
      toOutput: () => ({}),
    },
  },
}

Une action rend soit un Component, soit une interaction external_redirect. Une extension ne doit pas enregistrer une action sous le namespace d’une autre extension ou sous le namespace réservé ormuz.

journeyPresentation.show_provider_logo peut demander l’affichage du logo provider pour les actions de cette extension. Gardez cette présentation indépendante des garanties métier de l’action.

Redirections externes

Utilisez external_redirect lorsque le participant doit quitter temporairement l’expérience hébergée pour poursuivre chez le provider.

interaction: {
  type: 'external_redirect',
  navigation: 'core',
  start_command: 'start_payment',
  resume_command: 'resume_payment',
  retryable: true,
}

Les noms de commandes restent des identifiants snake_case stables. Ne faites pas porter à l’URL de redirection elle-même une sémantique de reprise qui devrait appartenir au contrat de l’action.

Localisation lazy

Une action localisée utilise le namespace plugin.<extension_key>. La locale par défaut doit correspondre à celle du manifeste, et chaque locale supportée fournit un loader lazy.

journeyI18n: {
  namespace: 'plugin.acme_pay',
  defaultLocale: 'en-US',
  resources: {
    'en-US': () => import('../i18n/en-US.js'),
    'fr-FR': () => import('../i18n/fr-FR.js'),
  },
}

Ne chargez pas toutes les traductions au démarrage global. Le bundle de l’extension et ses ressources sont résolus à la demande pour l’action courante.

Lifecycle navigateur

L’évaluation du module de l’extension ne doit produire aucun side effect navigateur : pas d’injection de script, pas de requête réseau, pas d’initialisation de SDK tiers et pas de redirection. Ces effets commencent uniquement quand l’action est réellement montée ou à la suite d’une interaction explicite.

Au démontage d’une action, nettoyez toutes les ressources qu’elle a créées :

• widgets, portals, overlays et iframes injectés hors de l’arbre React ;
• listeners globaux et observers ;
• timers et intervalles ;
• requêtes navigateur encore annulables ;
• callbacks asynchrones susceptibles d’écrire dans l’état d’une action suivante.

Un SDK ou son script peut rester en cache s’il devient inerte hors action. En revanche, son UI active doit rester rattachée à l’action qui l’a créée et disparaître avec elle. Ne corrigez jamais une fuite de lifecycle avec un sélecteur CSS global ou un nettoyage indiscriminé des éléments du provider.

Checklist avant intégration

• L’entrypoint navigateur n’a aucun side effect à l’import.
• Chaque action est namespacée par metadata.name.
• Le composant fonctionne après plusieurs montages/démontages successifs.
• Une action précédente ne peut plus modifier l’UI ou l’état courant.
• Les ressources i18n sont lazy et couvrent les locales déclarées.
• Les redirections utilisent des commandes stables et une stratégie de reprise explicite.
• Aucun SDK tiers n’est téléchargé uniquement parce que l’extension est installée.