Implementações headless em fases

Implementações 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.

Para saber mais sobre o uso de Einstein Activities no contexto do headless em fases, consulte Einstein Activities para implementações headless em fases.

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

O Plugin SLAS gerencia as sessões do B2C Commerce (associadas ao dwsid), bem como as sessões do SLAS (associadas a um access_token). O bridging de sessão vincula o dwsid e o access_token à mesma sessão do comprador.

O Plugin SLAS usa 2 métodos no bridging de sessão:

1. Bridge de sessão SLAS (API: getSessionBridgeAccessToken)
   • Usado pelo Plugin SLAS apenas para o Logon de novo visitante.
   • Não gera um novo dwsid após o bridging de sessão. Sendo assim, a loja (virtual) não requer um nova renderização e pode receber uma resposta 200 OK.
2. Bridge de sessão OCAPI (API: Obter sessão OCAPI)
   • Usado pelo Plugin SLAS para Logon de comprador registrado e Logon de token de atualização.
   • Gera um novo dwsid após o bridging de sessão. Sendo assim, a loja (virtual) requer uma atualização e precisa receber uma resposta de Redirecionamento 302.

A primeira etapa para criar uma implementação headless em fases é configurar seu aplicativo do PWA Kit para usar SLAS caso ainda não tenha feito isso. Siga as orientações no nosso guia Configurar o acesso à API.

Para habilitar uma implementação headless em fases com o SFRA, é preciso instalar o cartridge do Plugin SLAS. As orientações completas de instalação estão disponíveis no README do cartridge.

Considerações importantes para usuários de cartridge do SLAS

O cartridge do Plugin SLAS realiza diversas chamadas para várias APIs, o que pode afetar o desempenho da loja (virtual). Antes de adicionar o cartridge a uma loja (virtual) em Production, compare o desempenho da sua loja (virtual) com e sem o cartridge para decidir se é a solução adequada para você.

O cartridge também introduz um redirecionamento nas seguintes condições:

• Quando um comprador ainda não tem um cookie de sessão
• Quando o cookie de sessão de um comprador expirou
• Quando um mecanismo de pesquisa está indexando seu site

No momento, o cartridge só substitui o logon direto ao sistema do B2C Commerce quando as credenciais estão armazenadas na Salesforce.

Quando ele é usado com o plugin das listas de desejos, as listas de desejos de visitantes não são transferidas no logon para os usuários registrados.

Antes de usar o cartridge, consulte a página de problemas no GitHub.

Como o cartridge do Plugin SLAS foi criado para o SFRA, é necessário escrever um código adicional para usá-lo 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 registrados 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 2.7.x do modelo do Retail React App, você pode descomentar esta linha de código em auth.js para trocar para CookieStorage para armazenar tokens. Isso é obrigatório para o gerenciamento de sessões entre os sites do SFRA e do PWA Kit.

Você também precisa modificar o código em commerce-api/auth.js que chama a API de bridging de sessão após o logon do comprador. Para fazer isso, você tem que descomentar esta linha de código em auth.js.

Para poupar seu tempo, criamos uma versão alternativa do arquivo, com todas as alterações e a disponibilizamos no GitHub por meio de um gist público.

Caso seu projeto do PWA Kit tenha sido gerado com a versão 3.0.0 ou mais recente do modelo do Retail React App, as mudanças mencionadas acima estão habilitadas por padrão e nenhuma alteração de código é necessária.

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 de código de autorização, conforme definido pelo padrão OAuth 2.1. 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

Para garantir uma experiência de usuário simples durante a implementação em fases, você precisa de uma maneira de rotear o tráfego para duas origens diferentes: o ambiente do Managed Runtime e sua instância do B2C Commerce. Esse roteamento de tráfego pode ser realizado por uma rede de distribuição de conteúdo (CDN)

Imagine o cenário a seguir:

Você tem uma loja virtual SFRA executada emwww.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 você quer minimizar os riscos à planificação, você escolhe uma abordagem em fases para implementar a loja (virtual) do PWA Kit.

Você configura a CDN para enviar ao PWA Kit uma solicitação de 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, a CDN o redireciona para a página de checkout SFRA executada em www.mystorefront.com.

Para lidar com o roteamento de tráfego, você pode escolher a solução de CDN integrada (eCDN) da Salesforce (e com tecnologia do Cloudfare) ou uma CDN de outro fornecedor.

Caso você escolha a eCDN para rotear o tráfego para o Managed Runtime, use o endpoint createMrtRules da Commerce API.

A API é compatível com o roteamento de tráfego para o Managed Runtime usando as Rule Expressions (Expressões de regras) do Cloudflare. Ela é compatível com um subconjunto dos campos disponíveis na linguagem das regras. Os campos a seguir são compatíveis:

• http.host para fazer a correspondência com o nome do host
• http.request.uri.path para fazer a correspondência com o caminho da solicitação
• http.request.uri para fazer a correspondência com o caminho da solicitação e com a string de consulta
• http.cookie para fazer a correspondência com os cookies

Você pode solicitar 100 regras individuais por instância em zonas proxy e 100 regras individuais no total compartilhadas entre instâncias de Development e Production em zonas legadas.

• A eCDN só está disponível para instâncias de Development e Production e não está disponível para instâncias de Sandbox e On-Demand Sandbox (ODS).
• Instâncias de Staging precisam ser integradas à eCDN usando a eCDN API. Para obter mais informações, consulte Configurar a eCDN para Staging no Infocenter do B2C Commerce e este artigo do blog Rhino Inquisitor.
• A eCDN não é compatível com roteamento baseado em geolocalização.

Para ajudar na criação de suas regras de origem, reúna uma lista abrangente de rotas para as 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:

Crie uma rota de origem que inclua todas as rotas do PWA Kit na sua lista para encaminhar a solicitação ao ambiente do Managed Runtime (mystorefront.mobify-storefront.com no nosso exemplo).

O diagrama a seguir mostra a configuração da eCDN para o exemplo que descrevemos anteriormente:

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 da implementação 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, se o seu projeto do PWA Kit foi gerado com a versão 2.7.x ou com a versão 3.x do modelo do Retail React App sem usar a extensibilidade: remova o checkout do array de rotas.

Se o seu projeto do PWA Kit foi gerado com a versão 3.x do modelo do Retail React App usando extensibilidade, você pode substituir o arquivo overrides/app/routes.jsx para filtrar os links para páginas que não sejam do PWA Kit usando javascript. Criamos um exemplo da substituição do arquivo overrides/app/routes.jsx com todas as mudanças já feitas para filtrar as rotas de /cart e /checkout e disponibilizamos neste gist público do GitHub.

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.

Para instâncias PIG, os clientes podem usar a eCDN para “dividir” o tráfego entre as origens SFRA (ou SG) e MRT. No entanto, a eCDN não é compatível com instâncias SIG nem ODS. Para configurar e testar sites com implementações em fases localmente em instâncias SIG, os clientes precisam usar seu próprio proxy reverso ou CDN para dividir o tráfego.

Criamos um exemplo de aplicativo Node.js que pode ser usado para desenvolver e testar fluxos de comprador com implantação híbrida no PWA Kit e no SFRA/SiteGenesis. Instruções para configurar o proxy reverso estão descritas no README do repositório.

Criamos um vídeo de demonstração com as etapas para configurar implementações em fases em instâncias SIG:

[](https://salesforce.vidyard.com/watch/TNn6aYo7CRNQ8BXmRyYoNE “Implementações em fases no SIG")

Você pode configurar seu ODS para usar uma configuração com aliases semelhante à sua configuração em Production, o que ajuda a manter idênticas suas configurações locais e de produção. Por exemplo, configurar seu sandbox de forma que seu site híbrido esteja disponível no URI / assegura que os URLs enviados de pwa-kit não precisem ser traduzidos para incluir o ID do site. É assim que um site de Production é normalmente configurado.

Para habilitar aliases no Business Manager, siga as instruções neste módulo para Aliases de nome de host no Salesforce B2C Commerce no Trailhead.

Você pode configurar suas rotas do PWA Kit para prefixar todos os URLs de saída (por exemplo, aqueles destinados à SFRA) para incluir o prefixo /s/SiteID. Isso assegura que todas as instâncias recebam URLs do controlador da forma normalmente usada em sandboxes sem precisar configurar explicitamente os aliases de nome de host. É importante destacar que isso pode não ser adequado para a configuração de Production. Sendo assim, talvez seja melhor ter uma rota universal diferente para implantações de Production e Sandbox.

Para configurar prefixos de rota, atualize a rota de captura geral do PWA (/*) em app/routes.jsx ou overrides/app/routes.jsx.