Como atualizar seu cartucho do Salesforce Commerce Cloud

O que você vai aprender

Saiba como atualizar seu cartucho do Klaviyo para o Salesforce Commerce Cloud.

Você está usando uma versão do cartridge anterior à 23.7.0? Recomendamos que você atualize imediatamente para a versão 23.7.0 ou superior. Versões mais antigas do cartridge usam as APIs v1 e v2 da Klaviyo, que foram descontinuadas e não funcionam mais como esperado. Sempre recomendamos atualizar para a nossa versão mais recente (no momento, 25.7.0).

Antes de começar

A versão 23.7.0 inclui várias melhorias significativas, algumas das quais são mudanças de arquitetura relacionadas à forma como os eventos são acionados. As considerações especiais para atualizar de qualquer versão abaixo da 23.70 para qualquer versão acima dela estão detalhadas abaixo.

Entenda sua integração atual

É importante estar familiarizado com a integração atual do SFCC e com quais mudanças ou personalizações podem ter sido feitas especificamente para o seu site. O mais importante é considerar se os dados específicos do evento que você envia para o Klaviyo foram alterados ou incrementados e se você adicionou algum evento personalizado.

Recomendamos comparar o seu código que monta os dados de eventos com a versão anterior do cartridge da Klaviyo, disponível no Github da Klaviyo. Considerando que sua integração não tenha sido muito personalizada, você encontrará suas funções atuais de montagem de dados em int_klaviyo_core/cartridge/scripts/utils/klaviyo/klaviyoUtils.js e, para Confirmação de pedido, em int_klaviyo_core/cartridge/scripts/utils/klaviyo/emailUtils.js.

Anote quaisquer personalizações para poder reaplicá-las assim que o novo cartucho for instalado.

Conectar um sandbox do SFCC a uma conta de teste da Klaviyo

Se você ainda não criou uma conta secundária da Klaviyo para testes, separada da conta vinculada ao seu ambiente de produção do SFCC, faça isso. Em seguida, conecte seu ambiente de sandbox do SFCC à nova conta. Recomendamos concluir esta etapa usando sua versão anterior do cartridge da Klaviyo para que você possa verificar se os eventos estão sendo enviados e recebidos com sucesso pela sua conta secundária da Klaviyo antes de prosseguir com a atualização da sua base de código com o novo cartridge da Klaviyo.

Remova o código de cartucho anterior da Klaviyo

Se sua integração não tiver sido muito personalizada, você poderá remover a maior parte da integração anterior com a Klaviyo simplesmente excluindo as duas pastas de cartucho da Klaviyo: int_klaviyo_core e int_klaviyo (para Site Genesis) ou int_klaviyo_sfra (para SFRA) da base de código. No entanto, você também precisará remover qualquer código específico da Klaviyo que possa ter sido adicionado a arquivos de modelo e, possivelmente, a arquivos JavaScript.

Para o Site Genesis

As integrações Standard para o Site Genesis terão o seguinte código adicionado ao footer_UI.isml:

<isinclude template="components/footer/klaviyoFooter"/>

Eles também terão o seguinte bloco adicionado a minicart.isml, cart.isml e quaisquer outros arquivos isml de “carrinho”:

<isif condition="${pdict.CurrentHttpParameterMap.cartAction == 'add' || pdict.CurrentHttpParameterMap.cartAction
  == 'update'}">
   <isinclude url="${URLUtils.url('Klaviyo-RenderKlaviyoAddToCart')}"/>
</isif>

Para SFRA

As integrações Standard para SFCC terão o seguinte código adicionado a pageFooter.isml:

<isinclude template="klaviyo/klaviyoFooter"/>

Eles também terão o seguinte código adicionado à rota AddProduct no controller Cart.js:

 if(dw.system.Site.getCurrent().getCustomPreferenceValue('klaviyo_enabled')){
   var KlaviyoUtils = require('*/cartridge/scripts/utils/klaviyo/klaviyoUtils');
 KlaviyoUtils.trackAddToCart();
}

Tanto para Site Genesis quanto para SFRA, depois que as pastas do cartucho e os snippets de código mencionados acima forem removidos, é recomendável pesquisar no código-fonte a palavra "Klaviyo." Certifique-se de entender o que qualquer código relacionado à Klaviyo que ainda permaneça no seu código-fonte está fazendo antes de removê-lo, pois esses blocos podem representar personalizações que você precisará colocar de volta no lugar depois que o novo cartucho for instalado.

Remover serviços

A integração anterior terá criado um KlaviyoTrackService, KlaviyoTrackProfile e KlaviyoTrackCredentials em Administração > Operações > Serviço. Todos os três podem ser removidos com segurança, pois o processo de integração do novo cartucho Klaviyo criará novos serviços com nomes diferentes.

Não é essencial remover os serviços antigos, mas é recomendável limpá-los para evitar confusões no futuro.

Revise as preferências do site

O processo de integração do novo cartucho Klaviyo vai manter algumas das preferências anteriores do site da Klaviyo e também vai adicionar algumas novas. Confira as preferências do seu site no grupo de preferências do Klaviyo em Ferramentas do comerciante > Preferências do site > Preferências personalizadas > Klaviyo e verifique se alguma preferência personalizada foi adicionada especificamente ao seu site. Se você personalizou o cartucho para adicionar suas próprias configurações, você vai querer preservá-las. Para referência, aqui estão as quatro preferências de site que estão incluídas na integração anterior da Klaviyo:

• Klaviyo Enabled (ID: klaviyo_enabled)
  Indica se o Klaviyo está ativado ou desativado.
• Conta da Klaviyo (ID: klaviyo_account)
  Sua chave de API pública da Klaviyo, ou ID do site.
• Chave de API privada da Klaviyo (ID: klaviyo_api_key)
  Uma chave de API privada da Klaviyo.
• Tipo de imagem para Klaviyo (ID: klaviyo_image_size)
  Grande, pequena, miniatura etc.

Antes de configurar o novo cartucho, recomendamos fazer backup das suas preferências atuais do site exportando-as em Administração > Desenvolvimento do Site > Importação e Exportação do Site. Expanda Sites, depois Nome do site, e marque a caixa Preferências do site antes de inserir um nome de arquivo para exportá-las. Suas preferências atuais do Klaviyo não devem ser afetadas negativamente quando você instalar o novo cartridge mais tarde, mas é uma boa ideia fazer backup delas para consulta futura.

Remova os cartuchos da Klaviyo do caminho do cartucho

Remova int_klaviyo_core e int_klaviyo (Site Genesis) ou int_klaviyo_sfra (SFRA) do caminho do seu cartridge em Administração > Sites > Gerenciar sites > [Nome do site] > Configurações. Se você não realizar esta etapa, terá erros resultantes do SFCC procurando cartridges para carregar que não existem mais.

Verifique o console do desenvolvedor e o log do lado do servidor em busca de erros

Neste ponto, você não deve mais ter nenhum código da Klaviyo na sua base de código. Recomendamos revisar seu frontend, visitar páginas como Resultados de pesquisa, PLPs e PDPs e realizar ações como adicionar produtos ao carrinho, inserir informações e concluir o checkout. Ao fazer isso, fique de olho no Console do desenvolvedor para ver se algum novo erro é gerado. Faça o mesmo com o Log de solicitações. Se você estiver vendo novos erros relacionados à Klaviyo, há uma boa chance de que você não tenha removido completamente todo o código anterior da Klaviyo. É importante rastrear a origem de quaisquer novos erros e anotá-los antes de removê-los.

Instale o novo cartucho da Klaviyo

Siga as etapas descritas em Guia de introdução ao Salesforce Commerce Cloud para integrar o novo cartridge à sua base de código. Pode haver etapas que você não precisa concluir — por exemplo, sua instância do SFCC pode ou não já ter as conexões estabelecidas para a parte de OCAPI —, mas, em geral, você deve seguir cada etapa das integrações. Com certeza, você vai precisar substituir ambos os cartridges da Klaviyo e adicionar novamente o snippet de código.

Observe que, após importar metadata.zip, você terá quatro novas preferências do site, além das quatro que foram criadas pela versão anterior do cartridge. Suas preferências anteriores não devem ter sido afetadas pela importação das novas, mas é recomendável que você verifique novamente se todas as preferências do site da Klaviyo estão corretas antes de prosseguir.

Como você está fazendo upgrade de um cartridge anterior à versão 23.7.0, as novas preferências do site Label Events as SFCC e Send Added To Cart Event as ‘Add To Cart’ devem ser definidas como No e Yes, respectivamente. Isso continuará enviando eventos sem o rótulo de métrica Salesforce Commerce Cloud e usará o tipo de evento Add To Cart (em vez do novo Added to Cart). Definir essas duas preferências do site incorretamente vai causar uma quebra nos relatórios e, potencialmente, uma quebra dos fluxos existentes no Klaviyo.

Verifique se todos os eventos prontos para uso estão funcionando

Antes de tentar adicionar novamente quaisquer personalizações da sua integração anterior, verifique se a nova instalação do cartucho da Klaviyo está funcionando corretamente. Use o frontend para gerar eventos de Searched Site, Viewed Category, Viewed Product, Added To Cart, Started Checkout e Order Confirmation e, em seguida, verifique sua conta da Klaviyo para garantir que esses eventos estão sendo rastreados corretamente.

Verifique o console do desenvolvedor para ver se há novos erros que possam estar relacionados às integrações em todas as páginas que geram eventos do Klaviyo. Ative o registro detalhado do serviço marcando a caixa de seleção Communication Log Enabled em Administration > Operations > Services > KlaviyoEventService - Details e, em seguida, revise os arquivos de log do lado do servidor para verificar se não há erros e se os dados de eventos estão sendo gerados corretamente para cada tipo de evento.

Compare os dados de eventos com a produção

Agora, você deve comparar os dados de eventos nas suas contas de teste e de produção da Klaviyo para garantir que nada esteja faltando e que os valores atuais correspondam ao tipo esperado. É importante determinar se algum relatório ou fluxos será afetado pela nova integração. Você verá que propriedades adicionais agora estão sendo definidas e enviadas para a Klaviyo em comparação com a versão anterior do cartridge.

Adicionar novamente personalizações específicas do site

Agora você pode voltar a adicionar personalizações ao seu código da Klaviyo. Como há mudanças estruturais e arquitetônicas significativas no cartucho mais recente da Klaviyo, é improvável que você consiga simplesmente copiar e colar código personalizado diretamente no cartucho da Klaviyo.

Cada tipo de evento no cartridge da Klaviyo tem uma função getData que fica em um arquivo de script separado, nomeado de acordo com cada tipo de evento. Esses arquivos podem ser encontrados na pasta int_klaviyo_core/cartridge/scripts/klaviyo/eventData e são o local mais provável que você vai alterar para adicionar ou atualizar os objetos de dados que são passados para cada evento. Se você estiver criando novos eventos personalizados, recomendamos seguir o padrão estabelecido de adicionar código a controladores do lado do servidor (ou seja, diretamente no SiteGen ou via server.append no SFRA) que chama uma função getData de um arquivo de script dedicado ao novo evento e, em seguida, usa a função trackEvent para enviar esses dados para a Klaviyo via KlaviyoEventService.

Resultado

Agora você atualizou seu cartucho da Klaviyo para o Salesforce Commerce Cloud.

Recursos adicionais