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 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.

Configurer SLAS pour PWA Kit

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.

Installer la cartridge SLAS

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

Conseils pour les implémentations de SiteGenesis

Étant donné que la cartridge du plug-in SLAS 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.

Modifier PWA Kit pour utiliser des cookies

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 1.5.0 ou une version ultérieure du modèle Retail React App, vous pouvez changer cette ligne de commentaire en code dans auth.js ; aucune autre modification n’est nécessaire.

Pour les projets générés avant la version 1.5.0, vous devez apporter plusieurs modifications à commerce-api/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.

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. 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

Le schéma suivant illustre le flux d’autorisation modifié pour PWA Kit :

Le routage est un autre aspect important d’un déploiement headless progressif. Pour acheminer le trafic vers deux systèmes différents, nous devons configurer le CDN pour acheminer le trafic vers deux origines différentes : l’environnement Managed Runtime et votre instance B2C Commerce.

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 élaborez un plan de lancement d’une boutique PWA Kit en utilisant une approche progressive.

Le plan consiste à utiliser PWA Kit pour les pages situées en haut de l’entonnoir : page d’accueil (/), page de liste des catégories (/category) et 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 une personne décide d’effectuer un achat, vous la redirigez vers la page de checkout SFRA en cours d’exécution sur www.mystorefront.com.

Configurer les règles du CDN

Il est maintenant temps d’ajouter une origine à votre zone CDN pour les pages PWA Kit qui pointe vers votre environnement Managed Runtime (mystorefront.mobify-storefront.com).

Créez ensuite des règles de routage pour traiter le trafic en fonction du chemin d'URL. Commencez par rassembler une liste complète des itinéraires 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 :

Pour chacune des routes PWA Kit de votre liste, configurez votre CDN pour transférer la request à l’environnement Managed Runtime (mystorefront.mobify-storefront.com dans notre exemple de scénario).

Le schéma suivant montre comment configurer votre CDN :

Installer la cartridge de redirection (facultatif)

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.

Autres modifications apportées aux projets PWA Kit

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 : supprimez checkout du tableau de routes.

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.