Como atualizar seu cartucho do Salesforce Commerce Cloud

O que você vai aprender

Saiba como atualizar seu cartucho do Klaviyo Salesforce Commerce Cloud. 

O senhor está usando uma versão do cartucho anterior à 23.7.0? Recomendamos que o senhor faça a atualização imediata para a versão 23.7.0 ou superior. As versões mais antigas do cartucho usam as APIs v1 e v2 do Klaviyo, que foram desativadas e não funcionam mais como esperado. Sempre recomendamos a atualização para a versão mais recente (atualmente, 24.1.0).

Antes de começar

A versão 23.7.0 (lançada em 13 de julho de 2023) inclui uma série de melhorias significativas, algumas das quais são mudanças arquitetônicas sobre como os eventos são acionados. As considerações especiais para a atualização 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 as alterações ou personalizações que podem ter sido feitas especificamente para o seu site. Mais importante ainda, o senhor deve considerar se os dados de eventos específicos que envia para a Klaviyo foram alterados ou aumentados e se adicionou algum evento personalizado.

Recomendamos comparar seu código que reúne dados de eventos com a versão anterior do cartucho do Klaviyo, disponível no Github do Klaviyo. Supondo que sua integração não tenha sido muito personalizada, o senhor encontrará as funções atuais de montagem de dados em int_klaviyo_core/cartridge/scripts/utils/klaviyo/klaviyoUtils.js e, para Order Confirmation, em int_klaviyo_core/cartridge/scripts/utils/klaviyo/emailUtils.js.

Observe todas as personalizações para que o senhor possa reaplicá-las quando o novo cartucho for instalado.

Conectar uma sandbox SFCC a uma conta de teste do Klaviyo

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

Remova o código do cartucho Klaviyo anterior

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

Para o Site Genesis

As integrações padrão do 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 ao minicart.isml, cart.isml e quaisquer outros arquivos isml "cart":

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

Para SFRA

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

<isinclude template="klaviyo/klaviyoFooter"/>

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

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

Tanto no Site Genesis quanto no SFRA, depois que as pastas de cartuchos e os trechos de código mencionados acima forem removidos, é aconselhável pesquisar a palavra "Klaviyo" na base de código. Certifique-se de estar familiarizado com o que qualquer código relacionado ao Klavio que permaneça em sua base de código 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 Administration > Operations > Service. Todos os três podem ser removidos com segurança, pois o processo de integração do novo cartucho do Klaviyo criará novos serviços com nomes diferentes.

Não é essencial que os serviços antigos sejam removidos, mas é recomendável que o senhor os limpe para evitar confusões futuras.

Revisar as preferências do site

O processo de integração do novo cartucho do Klaviyo manterá algumas das preferências anteriores do site do Klaviyo e também adicionará algumas novas. Dê uma olhada nas preferências do seu site no grupo de preferências do Klaviyo em Merchant tools > Site Preferences > Custom Preferences > klaviyo e verifique se alguma preferência personalizada foi adicionada especificamente para o seu site. Se o senhor personalizou o cartucho para adicionar suas próprias configurações, deverá preservá-las. Para referência, aqui estão as quatro preferências de site incorporadas à integração anterior do Klaviyo:

• Klaviyo ativado (ID: klaviyo_enabled)
  Sinaliza se o Klaviyo está ativado ou desativado.
• Conta 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 do Klaviyo.
• Tipo de imagem para Klaviyo (ID: klaviyo_image_size)
  Grande, pequeno, miniatura, etc.

Antes de configurar o novo cartucho, recomendamos que o senhor faça backup das preferências atuais do site exportando-as em Administration > Site Development > Site Import & Export. Expanda Sites, depois seu Nome do site e marque a caixa Preferências do site antes de inserir um nome de arquivo para exportá-los. Suas preferências atuais do Klaviyo não devem ser afetadas negativamente quando o senhor instalar o novo cartucho posteriormente, mas é uma boa ideia fazer um backup delas para referência futura.

Remova os cartuchos Klaviyo do caminho do cartucho

Remova int_klaviyo_core e int_klaviyo (Site Genesis) ou int_klaviyo_sfra (SFRA) do caminho do cartucho em Administration > Sites > Manage Sites > [Site Name] > Settings. Se o senhor não executar essa etapa, receberá erros resultantes do fato de o SFCC procurar cartuchos para carregar que não existem mais.

Verifique se há erros no console do desenvolvedor e no log do servidor

Nesse ponto, o senhor não deve mais ter nenhum código do Klaviyo em sua base de código. Recomendamos que o senhor examine seu front-end, visite páginas como Resultados de pesquisa, PLPs e PDPs e execute ações como adicionar produtos ao carrinho, entrar 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 Registro de solicitações. Se estiver vendo novos erros relacionados ao Klaviyo, é bem provável que não tenha removido completamente todo o código anterior do Klaviyo. É importante rastrear a origem de todos os novos erros e anotá-los antes de removê-los.

Instale o novo cartucho Klaviyo

Siga as etapas descritas em Introdução ao Salesforce Commerce Cloud para integrar o novo cartucho em sua base de código. Pode haver etapas que não precisem ser concluídas - por exemplo, sua instância SFCC pode ou não ter as conexões já estabelecidas para a parte OCAPI - mas, em geral, o senhor deve seguir cada etapa da integração. Definitivamente, o senhor precisará substituir os dois cartuchos do Klaviyo e adicionar novamente os trechos de código. 

Observe que, depois de importar os metadados.zip, o senhor terá quatro novas preferências de site, além das quatro que foram criadas pela versão anterior do cartucho. Suas preferências anteriores não devem ter sido afetadas pela importação das novas, mas é recomendável que o senhor verifique novamente se todas as preferências do site do Klaviyo estão corretas antes de continuar.

Como o senhor está fazendo upgrade de um cartucho 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 do Salesforce Commerce Cloud e usará o tipo de evento Add To Cart (em oposição ao novo Added to Cart). A configuração incorreta dessas duas preferências de site resultará em uma interrupção dos relatórios e, possivelmente, em uma interrupção dos fluxos existentes no Klaviyo.

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

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

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

Comparar os dados do evento com a produção

Agora, o senhor deve comparar os dados do evento em suas contas de teste e de produção do Klaviyo para garantir que nada esteja faltando e que os valores atuais correspondam ao tipo esperado. É importante determinar se algum relatório ou fluxo será afetado pela nova integração. O senhor perceberá que outras propriedades estão sendo definidas e enviadas para o Klaviyo em comparação com a versão anterior do cartucho. 

Adicionar novamente personalizações específicas do site

Agora, o senhor pode começar a adicionar personalizações de volta ao código do Klaviyo. Como há grandes mudanças estruturais e arquitetônicas no mais novo cartucho do Klaviyo, é improvável que o senhor possa simplesmente copiar e colar o código personalizado diretamente no cartucho do Klaviyo.

Cada tipo de evento no cartucho do Klaviyo tem uma função getData que reside em um arquivo de script separado, nomeado para 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 o senhor alterará para adicionar ou atualizar os objetos de dados que são passados para cada evento. Se o senhor estiver criando novos eventos personalizados, recomendamos seguir o padrão estabelecido de adicionar código aos 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 ao Klaviyo por meio do KlaviyoEventService.

Resultado

O senhor já atualizou o cartucho do Klaviyo para o Salesforce Commerce Cloud. 

Recursos adicionais 

• Primeiros passos com o Salesforce Commerce Cloud
• Referência de dados do Salesforce Commerce Cloud
• Com que frequência as integrações sincronizam a referência
• Como entrar em contato com o suporte