Lançamentos headless em fases
Lançamentos em fases de tecnologias headless agora são possíveis para usuários do Storefront Reference Architecture (SFRA) e do SiteGenesis. Por exemplo, você pode implantar uma nova experiência arrojada para páginas de produtos usando o PWA Kit e manter o fluxo de checkout no SFRA até a próxima fase de sua transição headless. Essa abordagem em fases ajuda você a começar mais cedo e minimiza as interrupções ao longo do caminho para o headless.
Este guia descreve o uso das regras de roteamento e bridging de sessão para habilitar o PWA Kit a ser usado com um conjunto de páginas e o SFRA, com outro conjunto, sem afetar a experiência do usuário.
As instruções neste guia descrevem como combinar os fluxos do PWA Kit e do SFRA, mas também podem ser adaptadas para uso com o SiteGenesis.
Para permitir que os compradores naveguem de forma simples entre páginas que usam diferentes arquiteturas de loja virtual, é preciso usar uma técnica chamada bridging de sessão. Ela usa cookies para compartilhar os tokens de atualização e de sessão do comprador em diferentes sistemas.
Para fazer o bridging de sessão é preciso ter o Shopper Login and API Access Service (SLAS), uma nova solução com base em padrões usada para autorização e autenticação e acessada por solicitações HTTP. A autenticação do comprador com o SLAS é baseada no OpenID Connect; já a autorização para as APIs Shopper do Commerce Cloud é baseada no OAuth 2.
Quando um comprador navega em uma loja virtual headless, você usa o SLAS para solicitar um token de acesso e um de atualização, armazenando-os como cookies no navegador do comprador. É possível definir o cookie com o cabeçalho HTTP set-cookie ou com o JavaScript no lado do cliente. Quando o comprador migra de uma página do SFRA para uma página do PWA Kit (ou vice-versa), o cookie com o token de atualização é enviado na solicitação HTTP, e o código da loja usa esse token para fazer o logon do usuário.
A primeira etapa para criar um lançamento headless em fases é configurar seu aplicativo do PWA Kit para usar o SLAS caso ainda não tenha feito isso. Siga as orientações no nosso guia Configurar o acesso à API.
Para habilitar um lançamento headless em fases com o SFRA, é preciso instalar o cartridge de plug-in do SLAS. As orientações completas de instalação estão disponíveis no README do cartridge.
Além do bridging de sessão, o cartridge de plug-in do SLAS permite que você implemente outros recursos para compradores, como sessões de usuário que duram 90 dias e persistência do carrinho.
Como o cartridge de plug-in do SLAS foi criado para o SFRA, é necessário escrever um código adicional para usar com o SiteGenesis. Uma implementação do SiteGenesis pode aproveitar o código do cartridge em vários estágios dos fluxos de autenticação e autorização do comprador.
Como o cartridge usa o B2C Commerce Web Service Framework para lidar com as chamadas a SLAS API, uma implementação do SiteGenesis pode fazer solicitações aos serviços da web implementados pelo cartridge. Entre esses serviços da web estão logon e logout de cliente cadastrado e de visitante, token de atualização e mesclagem de carrinho do visitante. O cartridge também implementa um serviço que permite mesclar as sessões de API e da loja virtual.
Uma implementação do SiteGenesis também pode usar um hook (app.plugin.slas.login) personalizado para implementar o logon para visitantes e usuários cadastrados com o SLAS. Verifique o código personalizado no hook onSession do cartridge em dw.system.request.onSession para ver como ele substitui a Script API com o SLAS para o logon do comprador.
Para que o bridging de sessão seja possível com o PWA Kit, é preciso alterar o código que processa a autorização da API em commerce-api/auth.js para usar cookies em vez de armazenamento local.
Caso seu projeto do PWA Kit tenha sido gerado com a versão 1.5.0 ou mais recente do modelo do Retail React App, é possível remover o comentário nesta linha de código em auth.js, e não será necessário realizar outras alterações ao arquivo.
Para projetos gerados antes da versão 1.5.0, será preciso fazer várias alterações ao commerce-api/auth.js. Para poupar seu tempo, criamos uma versão alternativa do arquivo, com todas as mudanças já feitas, que está disponível em um gist público do GitHub.
O fluxo de autorização começa com o token de atualização. Se o cookie do token de atualização está disponível, o aplicativo do PWA Kit troca o token de atualização pelo token de acesso. Caso contrário, o aplicativo começa um fluxo de concessão para o código de autorização, conforme definido pelo padrão OAuth 2. Ele também segue o fluxo da chave de prova para troca de código (PKCE, da sigla em inglês).
Quando os novos tokens de acesso e de atualização são concedidos pelo SLAS, eles são armazenados em cookies pelo aplicativo. Em seguida, o aplicativo faz uma solicitação POST ao endpoint para criação de sessão do OCAPI (/session). Esse endpoint cria uma sessão que é usada pelo SFRA. O aplicativo armazena o token de sessão em um cookie.
Estes são os cookies criados pelo aplicativo do PWA Kit:
cc-nx-g: token de atualização do SLAS para o comprador visitante.cc-nx: token de atualização do SLAS para o comprador cadastrado.token: token de acesso do SLAS.dwsid: ID da sessão do Demandware
O diagrama a seguir apresenta o fluxo de autorização modificado para o PWA Kit:
Outro aspecto importante do lançamento headless em fases é o roteamento. Para atender o tráfego de dois sistemas diferentes, precisamos configurar a CDN para rotear o tráfego para duas origens diferentes: o ambiente do Managed Runtime e sua instância do B2C Commerce.
Imagine o cenário a seguir:
Você tem uma loja virtual SFRA executada em www.mystorefront.com. Você conhece as vantagens da arquitetura headless e quer usar o PWA Kit para criar experiências que gerem excelente engajamento e desempenho. Ao mesmo tempo, como quer minimizar os riscos à planificação, você desenvolve um plano para lançar a loja virtual do PWA Kit com uma abordagem em fases.
Seu objetivo é usar o PWA Kit para as páginas no topo do funil: a página inicial (/), a página com a lista de categorias (/category) e a página de detalhes do produto (/product). Essas páginas do PWA Kit estão implantadas em um ambiente do Managed Runtime executado em mystorefront.mobify-storefront.com. Quando o comprador decide fazer uma compra, você o redireciona para a página de checkout do SFRA executada em www.mystorefront.com.
Se você é cliente de uma CDN integrada (eCDN), entre em contato com o Suporte para configurar suas regras de roteamento.
Agora, vamos adicionar uma origem à sua zona da CDN para as páginas do PWA Kit que apontam para o ambiente do Managed Runtime (mystorefront.mobify-storefront.com).
Em seguida, crie as regras de roteamento para atender o tráfego com base no caminho do URL. Comece reunindo uma lista abrangente de rotas para páginas do PWA Kit. Para um projeto do PWA Kit baseado no modelo do Retail React App, as rotas são listadas em app/routes.jsx. Como o sistema de renderização no lado do servidor do PWA Kit usa rotas internas como proxies e ativos estáticos, você precisa incluir /mobify/* nas regras de roteamento.
No caso do nosso exemplo de cenário, as rotas a seguir precisam ser configurada em sua CDN:
Para cada uma das rotas do PWA Kit na sua lista, configure sua CDN para que a solicitação seja encaminhada para o ambiente do Managed Runtime (mystorefront.mobify-storefront.com no nosso exemplo).
O diagrama a seguir mostra como configurar a CDN:
Por padrão, o modelo do Retail React App para projetos do PWA Kit apresenta um padrão de roteamento de URL diferente do SFRA. Por exemplo, o caminho do URL para a página de detalhes do produto no Retail React App é /products/{productId}. Com o SFRA, o padrão é /{categoryId}/{productId}.
Recomendamos que você mude os padrões de roteamento em sua loja virtual do PWA Kit para que correspondam ao seu site SFRA. Caso você não consiga definir padrões de URL correspondentes para certas páginas (por exemplo, se o ID de categoria não estiver disponível no URL da página de listagem de produtos), use o Cartridge de redirecionamento para configurar redirecionamentos e solucionar esse problema. As orientações completas de instalação estão disponíveis no README do cartridge.
Para concluir o processo de configuração do lançamento headless em fases, é preciso fazer outras alterações em seu projeto do PWA Kit.
Por padrão, o PWA Kit usa a History API para navegação. Quando um comprador clica em um link criado com o componente <Link> do React Router, é acionada uma navegação “soft” até o componente que corresponde ao objeto de rota definido em app/routes.jsx. Para vincular uma página que não use o PWA Kit (alimentada pelo SFRA, por exemplo), é preciso remover todas as rotas que correspondam ao nome do caminho do URL em app/routes.jsx.
Por exemplo, remova o checkout da matriz de rotas.
Por fim, atualize a rota geral do PWA (/*) em app/routes.jsx. Substitua o PWA pelo componente <PageNotFound /> com um redirecionamento para a origem-padrão.