Déploiements headless échelonnés

Les déploiements échelonnés de technologies headless sont désormais possibles pour les utilisateurs de Storefront Reference Architecture (SFRA) et SiteGenesis. Par exemple, vous pouvez déployer une nouvelle expérience audacieuse pour les pages de produit avec PWA Kit, et conserver le flux de checkout sur SFRA jusqu'à la prochaine phase de votre transition headless. Cette approche échelonnée vous aide à vous lancer plus vite et minimise les perturbations sur votre parcours vers le headless.

Ce guide explique comment utiliser les règles de routage et le relais de session pour permettre à PWA Kit de gérer un ensemble de pages et à SFRA de gérer un autre ensemble de pages avec une expérience utilisateur entièrement fluide.

Pour en savoir plus sur l’utilisation d’Einstein Activities dans un contexte headless échelonné, consultez Einstein Activities pour des déploiements headless échelonnés.

Pour permettre aux acheteurs de naviguer en toute transparence entre les pages alimentées par différentes architectures de boutique en ligne, il est nécessaire d’utiliser une technique appelée relais de session. Le relais de session utilise des cookies pour partager des jetons d’actualisation de l’acheteur et des jetons de session sur différents systèmes.

La clé du déblocage du relais de session est le service SLAS (Shopper Login and API Access Service), une nouvelle solution basée sur des normes pour l’authentification et l’autorisation, accessible via des requests HTTP. L’authentification des acheteurs avec SLAS s’appuie sur OpenID Connect et l’autorisation pour les API Shopper de Commerce Cloud utilise OAuth 2.

Lorsqu’un acheteur navigue sur une boutique headless, vous utilisez SLAS pour demander un jeton d’accès et un jeton d’actualisation et les stocker sous forme de cookies dans le navigateur de l’acheteur. Vous pouvez définir le cookie à l’aide de l’en-tête HTTP set-cookie ou en JavaScript côté client. Quand l’acheteur passe d’une page SFRA à une page PWA Kit (ou inversement), le cookie contenant le jeton d’actualisation est envoyé avec la request HTTP et le code de la boutique peut utiliser le jeton d’actualisation pour connecter l’utilisateur.

Plugin SLAS gère les sessions B2C Commerce (associées à un dwsid) ainsi que les sessions SLAS (associées à un access_token). Liens de relais de session dwsid et access_token vers la même session d’acheteur.

Plugin SLAS utilise 2 méthodes de relais de session :

1. Relais de session SLAS (API : getSessionBridgeAccessToken)
   • Utilisé par Plugin SLAS pour la Connexion d’un nouvel invité uniquement.
   • Ne génère pas de nouveau dwsid après le relais de session, la boutique ne nécessite donc pas de nouveau rendu et peut recevoir une réponse 200 OK.
2. Relais de session OCAPI (API : Obtenir une session OCAPI)
   • Utilisé par Plugin SLAS pour la Connexion des acheteurs enregistrés et l’Actualisation de la connexion du jeton.
   • Génère un nouveau dwsid après le relais de session. La boutique nécessite donc une actualisation et doit recevoir une réponse de redirection 302.

La première étape d’un déploiement headless progressif consiste à configurer votre application PWA Kit pour utiliser SLAS (si ce n’est déjà fait). Suivez les instructions de notre guide Configurer l’accès aux API.

Pour activer un déploiement headless échelonné avec SFRA, vous devez installer la cartridge Plugin SLAS. Vous trouverez des instructions d’installation complètes dans le fichier README de la cartridge.

Points à retenir pour les utilisateurs de cartridges SLAS

La cartridge Plugin SLAS lance plusieurs appels vers diverses API, ce qui peut nuire aux performances de la boutique en ligne. Avant d’ajouter la cartridge à une boutique en production, comparez les performances de votre boutique avec et sans cartridge pour décider si vous souhaitez l’utiliser.

La cartridge introduit également une redirection dans les conditions suivantes :

• Si un acheteur n’a pas encore de cookie de session
• Si le cookie de session d’un acheteur a expiré
• Lorsqu’un moteur de recherche indexe votre site

Actuellement, la cartridge remplace uniquement la connexion directe au système B2C Commerce dans laquelle les informations d’identification sont stockées dans Salesforce.

Lorsqu’elles sont utilisées avec le plug-in de listes de souhaits, les listes de souhaits des invités ne sont pas transférées lors de la connexion à l’utilisateur enregistré.

Avant d’utiliser la cartridge, consultez la page des problèmes sur GitHub.

Étant donné que la cartridge SLAS Plugin est conçue pour SFRA, vous avez besoin d’écrire du code supplémentaire pour l’utiliser avec SiteGenesis. Une implémentation de SiteGenesis peut exploiter le code de la cartridge à différents points des flux d’authentification et d’autorisation des acheteurs.

Étant donné que la cartridge utilise le framework B2C Commerce Web Service pour gérer les appels d’API SLAS, une implémentation SiteGenesis peut lancer des requests aux services web implémentés par la cartridge. Ces services web incluent la connexion d’invités, la connexion de clients enregistrés, l’actualisation des jetons, la déconnexion et la fusion du panier d’un invité. La cartridge implémente également un service pour fusionner les sessions API et les sessions de la boutique en ligne.

Une implémentation de SiteGenesis peut également utiliser un hook personnalisé (app.plugin.slas.login) pour implémenter la connexion des invités et des utilisateurs enregistrés avec SLAS. Examinez le code personnalisé du hook onSession de la cartridge dans dw.system.request.onSession pour voir comment il remplace la Script API par SLAS pour la connexion de l’acheteur.

Pour permettre le relais de session avec PWA Kit, vous devez modifier le code de commerce-api/auth.js qui gère l’autorisation de l’API pour utiliser des cookies au lieu d’un stockage local.

Si votre projet PWA Kit a été généré avec la version 2.7.x du modèle Retail React App, vous pouvez décommenter cette ligne de code dans auth.js, afin de passer à CookieStorage pour stocker les jetons. C’est obligatoire pour gérer des sessions entre des sites SFRA et PWA Kit.

Vous devez également modifier le code dans commerce-api/auth.js qui appelle l’API session-bridge après la connexion de l’acheteur. Pour ce faire, vous devez décommenter cette ligne de code dans auth.js.

Pour vous faire gagner du temps, nous avons créé une autre version du fichier avec toutes les modifications en place et l’avons mise à disposition sur GitHub via un gist public.

Si votre projet PWA Kit a été généré avec la version 3.0.0 ou ultérieure du modèle Retail React App, les modifications mentionnées ci-dessus sont activées par défaut et aucune autre modification de code n’est requise.

Le flux d’autorisation commence par le jeton d’actualisation. Si le cookie du jeton d’actualisation est disponible, l’application PWA Kit échange le jeton d’actualisation pour un jeton d’accès. Sinon, l’application démarre un flux d’octroi de code d’autorisation, tel que défini par la norme OAuth 2.1. Elle suit également le flux PKCE (Proof Key for Code Exchange).

Lorsque le nouveau jeton d’accès et le nouveau jeton d’actualisation sont accordés par SLAS, l’application les stocke dans des cookies. L’application envoie ensuite une request POST au point de terminaison de création de session OCAPI (/session). Ce point de terminaison crée une session qui est utilisée par SFRA. L’application stocke le jeton de session dans un cookie.

Cookies créés par l’application PWA Kit :

• cc-nx-g : jeton SLAS d’actualisation de l’acheteur invité
• cc-nx : jeton SLAS d’actualisation de l’acheteur enregistré
• token : jeton d’accès SLAS
• dwsid : identifiant de session Demandware

Pour garantir la fluidité de l’expérience utilisateur lors d’un déploiement échelonné, vous avez besoin d’un moyen de router le trafic vers deux origines différentes : l’environnement Managed Runtime et votre instance B2C Commerce. Ce routage du trafic peut être géré par un réseau de diffusion de contenu (CDN).

Imaginez le scénario suivant :

Vous avez déjà une boutique SFRA en cours d’exécution sur www.mystorefront.com. Vous connaissez les avantages de l’architecture headless et vous souhaitez tirer parti de PWA Kit pour proposer des expériences performantes et stimulantes. En parallèle, vous souhaitez minimiser les risques liés à la planification, de sorte que vous choisissez une approche échelonnée pour déployer votre boutique en ligne PWA Kit.

Vous configurez le CDN pour envoyer une request de page en haut de l’entonnoir vers PWA Kit : la page d’accueil (/), la page de liste des catégories (/category) et la page de détails du produit (/product). Ces pages PWA Kit sont déployées dans un environnement Managed Runtime exécuté sur mystorefront.mobify-storefront.com. Lorsque l’acheteur décide d’effectuer un achat, le CDN le redirige vers la page de checkout SFRA existante fonctionnant sur www.mystorefront.com.

Pour gérer le routage du trafic, vous pouvez choisir la solution de CDN intégré (eCDN) de Salesforce (optimisée par Cloudflare) ou choisir un CDN d’un autre fournisseur.

Pour utiliser l’eCDN afin de router le trafic vers Managed Runtime, utilisez le point de terminaison de l’API Commerce createMrtRules.

L’API prend en charge le routage du trafic vers Managed Runtime à l’aide des expressions de règles de Cloudflare. Elle prend en charge un sous-ensemble des champs disponibles dans le langage des règles. Les champs suivants sont pris en charge :

• http.host pour la correspondance avec le nom d’hôte
• http.request.uri.path pour la correspondance avec le chemin de la request
• http.request.uri pour la correspondance avec le chemin de la request et la chaîne de requête
• http.cookie pour la correspondance avec les cookies

Vous pouvez requérir 100 règles individuelles par instance sur les zones proxy et 100 règles individuelles au total, partagées entre les instances development/production sur les anciennes zones.

• L’eCDN est disponible uniquement pour les instances Production et Development ; il n’est pas disponible pour les instances sandbox ou ODS.
• Les instances Staging doivent être intégrées à l’eCDN à l’aide de l’API eCDN. Pour en savoir plus, consultez Configurer l’eCDN pour une instance Staging sur l’Infocenter B2C Commerce et cet article sur le blog Rhino Inquisitor.
• L’eCDN ne prend pas en charge le routage sur la base de la géolocalisation.

Pour vous aider à concevoir vos règles d’origine, rassemblez une liste complète de routes pour les pages PWA Kit. Pour un projet PWA Kit basé sur le modèle Retail React App, les routes sont répertoriées dans app/routes.jsx. Étant donné que le système de rendu côté serveur pour PWA Kit utilise des routes internes pour les proxys et les actifs statiques, vous devez également inclure /mobify/* dans les règles de routage.

Pour notre exemple de scénario, les routes suivantes doivent être configurées dans votre CDN :

Créez une règle d’origine qui inclut toutes les routes PWA Kit de votre liste pour transférer la request à l’environnement Managed Runtime (mystorefront.mobify-storefront.com dans notre exemple de scénario).

Le diagramme suivant montre la configuration de l’eCDN pour l’exemple de scénario décrit précédemment :

Par défaut, le modèle Retail React App pour les projets PWA Kit a un autre modèle de routage des URL que celui de SFRA. Par exemple, voici le chemin d'URL d’une page de détails de produit dans l’application Retail React App : /products/{productId}. Avec SFRA, vous aurez ce schéma : /{categoryId}/{productId}.

Nous vous recommandons de modifier les modèles de routage dans votre boutique PWA Kit afin qu’ils correspondent à ceux de votre site SFRA. Si vous ne parvenez pas à faire correspondre les modèles d’URL d’une page spécifique (comme la page de liste des produits lorsque l’identifiant de catégorie n’est pas disponible dans l’URL), vous pouvez utiliser la cartridge de redirection pour configurer les redirections qui comblent cette lacune. Vous trouverez des instructions d’installation complètes dans le fichier README de la cartridge.

Pour terminer le processus de configuration d’un déploiement headless progressif, il reste quelques modifications à apporter à votre projet PWA Kit.

Par défaut, PWA Kit utilise History API pour la navigation. Lorsqu’un acheteur clique sur un lien créé avec le composant <Link> de React Router, il déclenche une navigation logicielle vers le composant correspondant au chemin dans l’objet route défini dans app/routes.jsx. Pour créer un lien vers une page externe à PWA Kit (une page créée à l’aide de SFRA, par exemple), vous devez supprimer de app/routes.jsx toute route correspondant au chemin d’accès de l’URL.

Par exemple, si votre projet PWA Kit a été généré avec la version 2.7.x ou 3.x du modèle Retail React App sans utiliser l’extensibilité : supprimez le checkout du tableau des routes.

Si votre projet PWA Kit a été généré avec la version 3.x du modèle Retail React App à l’aide de l’extensibilité, vous pouvez remplacer le fichier overrides/app/routes.jsx pour filtrer les liens vers les pages autres que PWA Kit à l’aide de javascript. Nous avons créé un exemple de remplacement du fichier overrides/app/routes.jsx avec toutes les modifications en place pour filtrer les routes /cart et /checkout et l’avons mis à disposition sur GitHub via un gist public.

Enfin, mettez à jour la route PWA catch-all (/*) dans app/routes.jsx. Remplacez le composant PWA par une redirection vers l’origine par défaut.

Pour les instances PIG, les clients peuvent utiliser l’eCDN pour « diviser » le trafic entre les origines SFRA (ou SG) et MRT. L’eCDN ne prend toutefois pas en charge les instances SIG et ODS. Pour configurer et tester localement le déploiement échelonné de sites sur des instances SIG, les clients doivent utiliser leur propre CDN ou proxy inverse afin de diviser le trafic.

Nous avons créé un exemple d’application Node.js. Vous pouvez l’utiliser pour développer et tester des flux d’acheteurs pour un déploiement hybride sur PWA Kit et SFRA/SiteGenesis. Les instructions d’installation et de configuration pour la mise en place du proxy inverse figurent dans le fichier README du dépôt.

Nous avons réalisé une vidéo de démonstration présentant les étapes de configuration des déploiements échelonnés sur les instances SIG :

Vous pouvez configurer votre ODS afin d’utiliser une configuration d’alias similaire à votre configuration de production. Cela peut vous aider à conserver des configurations locales et de production identiques. Par exemple, en configurant votre sandbox de sorte que votre site hybride soit disponible à l’URI /, vous vous assurez que les URL envoyées par pwa-kit n’ont pas besoin d’être traduites pour inclure l’identifiant du site. C’est généralement ainsi qu’un site de production est configuré.

Pour activer les alias dans Business Manager, suivez les instructions de ce module pour les alias de nom d’hôte Salesforce B2C Commerce sur Trailhead.

Vous pouvez configurer les routes de votre PWA Kit pour modifier toutes les URL sortantes (par exemple, celles destinées à SFRA) afin d’inclure le préfixe /s/SiteID. Cela garantit que votre instance reçoit les URL du controller d’une manière normalement utilisée sur les sandboxes sans avoir à configurer explicitement des alias de noms d’hôte. Notez que cela peut ne pas convenir à une configuration de production ; vous souhaiterez donc peut-être avoir une route par défaut (catch-all) différente pour les déploiements en production et sur sandbox.

Pour configurer les préfixes de route, mettez à jour la route par défaut de PWA (/*) dans app/routes.jsx ou overrides/app/routes.jsx.