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. As versões mais antigas do cartridge usam as APIs v1 e v2 da Klaviyo, que foram descontinuadas e não funcionam mais como esperado. Recomendamos fazer upgrade para a versão mais recente na página de releases do GitHub da Klaviyo.
Antes de começar
A versão 23.7.0 inclui várias melhorias significativas, algumas delas relacionadas a mudanças de arquitetura na forma como os eventos são acionados. As etapas abaixo explicam como fazer upgrade de uma versão anterior à 23.7.0 para a versão 23.7.0 ou posterior. Conclua o upgrade e os testes em um sandbox do SFCC antes de fazer alterações no seu site de produção.
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 código que monta os 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 altamente 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 do 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 do Klaviyo para testes, separada da conta vinculada ao seu ambiente de produção do SFCC, você deve fazer isso. Em seguida, conecte seu ambiente sandbox do SFCC à nova conta, usando as chaves de API pública e privada dessa conta nas configurações do cartridge da sandbox. Recomendamos concluir esta etapa usando sua versão anterior do cartridge do Klaviyo para que você possa verificar se os eventos estão sendo enviados e recebidos com sucesso pela sua conta secundária do Klaviyo antes de prosseguir para atualizar sua base de código com o novo cartridge do 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 SFRA 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, um KlaviyoTrackProfile e um KlaviyoTrackCredentials em Administração > Operações > Serviços. Todos os três podem ser removidos com segurança, já que o processo de integração do novo cartridge da 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 do Klaviyo (ID: klaviyo_api_key)
Uma chave de API privada do 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.
Não copie/cole simplesmente as novas pastas de cartucho sobre as antigas. Conforme as instruções acima, exclua completamente as pastas antigas antes de adicionar as novas.
Importar o arquivo metadata.zip adiciona novas preferências do site junto às 4 listadas acima. Revise todas as preferências do site do Klaviyo e confirme seus valores existentes antes de prosseguir. Configure Klaviyo Email Selectors e Checkout Email Selector para os campos de e-mail do seu site para que o Klaviyo possa identificar visitantes e rastrear a atividade de checkout.
Como você está atualizando 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 Não e Sim, respectivamente. Isso continuará enviando eventos sem o rótulo da 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 resultará em uma quebra nos relatórios e, possivelmente, uma quebra dos fluxos existentes na 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.
Depois de restaurar suas personalizações, repita as verificações de eventos e erros no sandbox, incluindo quaisquer eventos e propriedades personalizados usados pelos seus fluxos. Quando o teste estiver concluído, implante a atualização testada na produção usando as chaves de API e as preferências do site da conta de produção do Klaviyo e, em seguida, verifique se os eventos chegam à conta de produção com os nomes e dados esperados.
Resultado
Agora você atualizou seu cartucho da Klaviyo para o Salesforce Commerce Cloud.
Recursos adicionais
- Guia de introdução ao Salesforce Commerce Cloud
Saiba como integrar o Salesforce Commerce Cloud ao Klaviyo. A integração de cartridge e API do Klaviyo permite que sites que usam o Salesforce Commerce Cloud (antes Demandware) se conectem rapidamente e enviem dados em tempo real e históricos ao Klaviyo. Quando você integrar o Klaviyo ao Salesforce Commerce Cloud (SFCC), o Klaviyo começará a rastrear em tempo real ações que as pessoas realizam, como navegação no site, rastreamento de pesquisa, visualização de produtos, visualização de categorias, adição de itens ao carrinho, checkout e pedidos.
- Referência de dados do Salesforce Commerce Cloud
Saiba quais dados são sincronizados do Salesforce Commerce Cloud com a Klaviyo após você ativar a integração do Salesforce Commerce Cloud da Klaviyo e como você pode visualizá-los.
- Referência de frequência de sincronização das integrações
Aprenda quais dados são sincronizados a partir de uma integração específica da Klaviyo e com que frequência a sincronização é executada. Organizamos essas integrações por plataformas de e-commerce, ESP e outras integrações de dados.
- Como entrar em contato com o suporte
Oferecemos suporte por e-mail e chat ao vivo para clientes de todos os planos pagos.