Como configurar o Klaviyo Customer Hub com o Headless Shopify

O que você vai aprender

Você conectará o Klaviyo Customer Hub a uma vitrine Shopify sem cabeça, escolherá um método de login e publicará o Hub para que os compradores possam acessá-lo em todo o site.

Antes de começar

Pré-requisitos 

⚠️ Observação: você deve entrar em contato com seu representante, CSM ou Klaviyo suporte para habilitar o suporte Headless Shopify para sua conta Klaviyo antes de continuar, para que possa acessar as configurações necessárias. Como entrar em contato com o suporte

1. Um storefront Shopify sem cabeça com acesso ao Storefront API (token de acesso público / chave pública do Storefront API em Shopify's Headless Administrador).
2. Seu ID da empresa Klaviyo (usado pelo carregador de JavaScript no site).
3. Decisão sobre o login do comprador: API da conta de cliente da Shopify ou senha de uso único (OTP) da Klaviyo.
   1. Se você estiver usando contas existentes, tenha em mãos as rotas de login, logout e (opcional) Gerenciar conta e Gerenciar endereços da sua loja.
4. Capacidade de editar o código da loja e implementar alterações.
5. Quem pode configurar isso: Você precisa de uma função de conta que possa editar as configurações do Klaviyo Customer Hub e publicar o widget (Proprietário, Administrador ou uma função personalizada que tenha acesso de gravação ao Conteúdo e à chave de API). 

Visão geral

O Klaviyo Customer Hub é uma sobreposição em todo o site que oferece aos compradores acesso mais rápido às ações da conta e a ferramentas úteis de compras. No caso da Shopify sem interface, você conecta o script do Klaviyo no local, escolhe um método de login (API de contas do cliente ou OTP do Klaviyo) e, opcionalmente, adiciona:

1. Produto ativo: mostra o produto que um comprador está visualizando no Hub.
2. Recently Viewed: lista os produtos vistos recentemente usando o rastreamento da Klaviyo.
3. Widget de favoritos e FAQs: renderizar nos PDPs e dentro do Hub.  

Use o Klaviyo Customer Hub quando você quiser uma camada de assistência on-page que impulsione a descoberta de produtos e o checkout mais rápido, melhorando a conversão e o Valor - tempo de vida.

Configuração

1 - Configurar as definições do Klaviyo Customer Hub

Primeiro, siga o Guia de introdução ao Klaviyo Customer Hub e conclua o assistente de integração, como em qualquer outra configuração. Quando isso for concluído, acesse o Klaviyo Customer Hub > Settings. Você verá a seção de configuração do Headless Shopify. 

Cole a chave pública do Storefront API do administrador sem cabeça do Shopify(token de acesso público). 

Em Shopper login, selecione Shopify Customer Account API (recomendado para que todos os aplicativos da sua loja possam compartilhar o login da Shopify) ou Klaviyo One Time Password (OTP, funciona apenas com o Klaviyo e não fará o login dos compradores em nenhum outro aplicativo). 

Se você selecionar a API da conta de cliente da Shopify, insira também as rotas de login, logout e gerenciar conta/gerenciarendereços opcionais da vitrine (usadas para redirecionamentos entre o Hub e seu site). 

Visibilidade da publicação: defina o Klaviyo Customer Hub como Live. 

2 - Carregue o JavaScript do Klaviyo Customer Hub (instruções do desenvolvedor)

Dica: Se você já executa os recursos no local do Klaviyo, talvez já tenha um carregador instalado. Confirme antes de adicionar um segundo script. 

Crie o arquivo /public/customerHub.js (ou equivalente) com o seguinte carregador (substitua COMPANY_ID pela sua Klaviyo chave pública API de, também conhecida como ID da sua empresa):

// customerHub.js
// TODO: Configuração
const COMPANY_ID = '';
const script = document.createElement('script');
script.src = `https://static.Klaviyo.com/onsite/js/${COMPANY_ID}/Klaviyo.js`;
script.async = true;
script.onload = () => { console.log('Klaviyo JS script loaded successfully'); };
script.onerror = () => { console.error('Failed to load Klaviyo JS script'); };
document.body.appendChild(script);

O script no local é carregado em todas as páginas. Procure a mensagem do console: "O script JS do Klaviyo foi carregado com sucesso".  Em seu layout raiz (por exemplo, root.tsx), incluir o carregador:

// root.tsx
return (
  <html>
    <body>
      < script src="/customerHub.js" defer></script>
    </body>
  </html>
)

Após essa etapa, window.customerHubApi fica disponível nas páginas em que o Hub é executado. 

3 - Mostrar o produto ativo no Klaviyo Customer Hub

Adicione a chamada de hidratação em sua página de detalhes do produto (PDP) para que o produto atual apareça no Hub:

<!-- products.tsx -->
< script type="text/javascript"> 
 (function() {
 function waitForCustomerHubApi() {
 return new Promise((resolve) => {
 const check = () => {
 if (window.customerHubApi && window.customerHubApi.hydrateProduct) {
            resolve();
          } else {
            requestAnimationFrame(check);
          }
        };
 check();
 });
 }
 waitForCustomerHubApi().then((() => {
      window.customerHubApi.hydrateProduct("your-product-handle");
    });
 })();
</script>

OHub deve agora exibir um cartão de produto adicional para o PDP que o comprador está visualizando na guia "Chat" se você a tiver ativado. 

4 - Habilitar produtos vistos recentemente no Klaviyo Customer Hub

Implemente o rastreamento de produtos visualizados para que o Hub possa preencher os itens visualizados recentemente e você possa usar a métrica em outras partes do Klaviyo. Os seguintes snippets de rastreamento também podem ser adicionados diretamente à sua vitrine; as instruções podem ser encontradas aqui em nossa documentação para desenvolvedores do Klaviyo: Integrar uma plataforma de comércio eletrônico sem uma predefinição Klaviyo integrações.

5 - Ativar a aquisição do link da conta

Para que o Klaviyo Customer Hub do Klaviyoseja aberto ao clicar no ícone da conta no cabeçalho da sua vitrine, você já precisa ter um a-tag existente que faça referência a um link com /account (nesse caso, nós o substituiremos automaticamente para você). Ou você também pode definir manualmente o link do ícone para apontar para #k-hub a fim de abrir a gaveta.

6 - Configure o Klaviyo Customer Hub com a autenticação de contas de clientes API (recomendado)

Para usar as contas de clientes e a configuração de autenticação da sua vitrine existente, o Klaviyo Customer Hub exigirá que você adicione uma nova rota API à sua vitrine, que lidará com a passagem segura do token de acesso de um comprador para nossos serviços. O importante é que a nova rota API seja nomeada e possa ser acessada com '/API/authenticateCustomerHub'.

Observação: o exemplo de snippet de código a seguir é para a estrutura Hydrogen da Shopify; vitrines mais personalizadas podem exigir algumas soluções alternativas adicionais, mas a abordagem geral será descrita aqui.

// ./app/routes/API.authenticateCustomerHub.js
// TODO: Configuração
const COMPANY_ID = '';
export async function action({context}) {
 // Extraia o cliente da conta do cliente API do contexto da sua loja
 const {customerAccount} = context;
 try {
 // Obtenha o token de acesso para o cliente atual
 const accessToken = await customerAccount.getAccessToken();
    Se (!accessToken) {
 return new Response(JSON.stringify({message: 'User not logged in'}), {
        status: 200,
      });
 }
   Enviar o token de acesso para o Klaviyo Customer Hub API
    const response = await fetch(
 'https://atlas-app.services.klaviyo.com/api/onsite/headless-shopify-login',
      {
 method: 'POST',
 headers: {
          'Content-Type': 'application/json',
        },
 body: JSON.stringify({
          access_token: accessToken,
          company_id: COMPANY_ID,
        }),
 },
 );
 const responseData = await response.text();
    // Retornar a resposta real do Klaviyo Customer Hub com o mesmo código de status
 return new Response(responseData, {
 status: response.status,
      headers: {
        'Content-Type':
          response.headers.get('content-type') || 'application/json',
      },
 });
 } catch (error) {
 return new Response(null, {status: 500});
 }
}

Depois que isso for configurado, bem como as rotas da vitrine definidas nas configurações de Klaviyo, o Klaviyo Customer Hub poderá se vincular à configuração de autenticação existente e fornecer um ponto de entrada perfeito para as contas de clientes existentes.

7 - Adicione o widget Favorites (recomendado)

Tanto os Favoritos quanto as Perguntas frequentes funcionarão na gaveta do Klaviyo Customer Hub. No entanto, você pode adicionar esse widget também em PDPs para obter engajamento adicional.

Para adicionar um ponto de entrada de Favoritos nos PDPs e dentro do Hub:

// products.tsx
// Exemplo de identificadores:
// id: gid://Shopify/Product/12345
// data-product-id: 12345
const gid = "gid://Shopify/Product/12345";
const productId = gid.divisão('/').pop();

return (
 < div
 className="kl-hub-favorites-slot"
 data-product-id={productId}
  />
 )

Os compradores agora podem clicar em Adicionar aos favoritos nos PDPs; o item aparece nos itens favoritos do Hub. 

8 - Adicione blocos de perguntas frequentes (recomendado)

Da mesma forma que adicionar Favoritos, adicionar blocos de FAQ é tão simples quanto adicionar uma div na página do produto com o ID do produto passado para renderizar as FAQs que você pode editar e projetar no Klaviyo.

Adicione um bloco de FAQs específico do produto que você criou no Klaviyo:

// products.tsx
// Exemplo:
const gid = "gid://Shopify/Product/12345";
const productId = gid.divisão('/').pop();

return (
 < div className="klaviyo-faqs-slot" data-product-id={productId} />
 )

Os chips/botões de perguntas frequentes agora devem ser renderizados nos PDPs se estiverem configurados e forem editáveis no Klaviyo

Práticas recomendadas

1. Publique na produção somente após a verificação - mantenha a preparação oculta até que o controle de qualidade seja concluído; em seguida, defina o Live para expor o Hub. Impacto: menos problemas de suporte, menor tempo de retorno do investimento.
2. Sempre hidrate o produto ativo nos PDPs - mantém o contexto do produto visível no Hub e estimula a adição ao carrinho. Impacto: taxa de conversão, taxa de recompra.
3. Implementar rastreamento de produtos visualizados antecipadamente - preenche o Recently viewed e desbloqueia o fluxo baseado em navegação. Impacto: engajamento e receita da recuperação de navegação.
4. Adicionar favoritos - cria uma ação de salvamento de baixo atrito e uma lista restrita persistente. Impacto: visitas repetidas, adicionar ao carrinho.
5. Use perguntas frequentes para objeções - responda perguntas sobre remessa, materiais ou devoluções em linha para reduzir o abandono. Impacto: taxa de conversão.
6. Prefira a autenticação do lado do servidor com a API de contas de clientes quando disponível - melhora a continuidade para os compradores conectados. Impacto: qualidade da experiência, deflexão do suporte.  

Medindo o sucesso

Onde você pode ver os resultados: Use o Analytics > métrica para monitorar a atividade do produto visualizado e o desempenho do fluxo/campanha downstream. Use seu painel de receita de comércio eletrônico para acompanhar as alterações de conversão e valor médio de pedido após ativar o Klaviyo Customer Hub. Principais métricas a serem observadas: taxa de conversão do PDP, taxa de adição ao carrinho, sessões com aberturas do Hub (se instrumentadas), receita por destinatário (taxa de recompra) e receita orientada pela navegação vinculada a eventos de produtos visualizados. Lista de verificação de correções rápidas: Baixa Atividade visualizada recentemente? Verifique se o snippet de rastreamento Viewed Product está sendo acionado e se os eventos são atribuídos ao perfil. Você está com pouca adição ao carrinho no Hub? Certifique-se de que a hidratação do Active Product seja executada em todos os PDPs e que as variantes/preços estejam corretos. Você adiciona alguns favoritos? Mova o slot Favoritos para perto das principais CTAs do PDP e confirme se o ID do produto de dados corresponde ao produto.  

Solução de problemas

Sintoma: o Klaviyo Customer Hub não aparece no site.

Causa provável: O script não está sendo carregado ou o hub está oculto.

Correção: confirme se o customerHub.js é carregado (verifique o console), se o ID da empresa está definido e se a visibilidade do Klaviyo Customer Hub está ativa nas configurações do Klaviyo Customer Hub > . 

Sintoma: O console mostra "Falha ao carregar o script JS do Klaviyo".

Causa provável: URL incorreto do script ou ID da empresa ausente.

Correção: Verifique se https://static.Klaviyo.com/onsite/js/<COMPANY_ID>/Klaviyo.js e se COMPANY_ID está preenchido. 

Sintoma: O cartão de produto ativo não é exibido no hub nos PDPs.

Causa provável: hydrateProduct não chamado ou identificador de produto incorreto.

Correção: Certifique-se de que o loop de espera seja executado e chame window.customerHubApi.hydrateProduct("<handle>" ) com a alça correta do produto. 

Sintoma: A seção de visualizações recentes está vazia.

Causa provável: O rastreamento do produto visualizado não foi implementado.

Correção: adicione o snippet de rastreamento Viewed Product do guia do desenvolvedor e verifique os eventos no Klaviyo. 

Sintoma: O widget Favoritos ou Perguntas frequentes não é renderizado no PDP.

Causa provável: Contêiner ausente ou atributo incorreto.

Correção: adicione <div class="kl-hub-favorites-slot" data-product-id="..."> e/ou <div class="klaviyo-faqs-slot" data-product-id="..."> com o ID de produto correto. 

Sintoma: Ao clicar no ícone da conta, você não abre o Hub.

Causa provável: O link do cabeçalho não está apontando para /account ou #k-hub.

Correção: Certifique-se de que a âncora da conta use /account (aquisição automática) ou defina href="#k-hub". 

Sintoma: Os compradores não são reconhecidos como entrantes no Hub.

Causa provável: Rota /API/authenticateCustomerHub ausente ou falha na solicitação API.

Correção: implemente o exemplo do Hydrogen (ou o equivalente em sua estrutura), envie access_token e company_id para o ponto de extremidade de login do Klaviyoe retorne a resposta. 

Perguntas frequentes

P: Preciso usar a API de contas de clientes da Shopify para fazer login?

R: Não. Em vez disso, você pode usar a One Time Password (OTP) do Klaviyo. Se você já usa contas da Shopify, conecte-se por meio da API de contas de clientes para ter uma experiência perfeita. 

P: Quais rotas de fachada de loja eu preciso fornecer?

R: Se você estiver usando as contas existentes, forneça as rotas de login e logout; Gerenciar conta e Gerenciar endereços são opcionais para vinculação mais profunda. 

P: Onde posso encontrar a chave pública da API do Storefront?

R: No administrador sem cabeça do site Shopify, em Storefront API > Public access token (também chamado de chave pública do Storefront API ). 

P: O Klaviyo Customer Hub pode assumir o ícone da minha conta?

R: Sim. Se o link da conta do seu cabeçalho usar /account, o Klaviyo Customer Hub poderá ser aberto automaticamente; você também pode apontá-lo para #k-hub. 

P: O Shopify Hydrogen é necessário?

R: Não. O exemplo de autenticação usa o Hydrogen, mas qualquer estrutura pode implementar uma rota de servidor em /API/authenticateCustomerHub que publica o token de acesso e o company_id em Klaviyo. 

P: Os Favoritos e as Perguntas Frequentes podem ficar nos PDPs e dentro do Hub?

R: Sim. Adicione as respectivas divs de contêiner nos PDPs; elas também aparecerão na gaveta do Hub.