Como configurar o Klaviyo Customer Hub com Shopify headless

Conecte o Klaviyo Customer Hub à sua vitrine headless do Shopify. Ative o login, exiba widgets (Favoritos, Perguntas frequentes) e potencialize experiências de produto com atividade/vistos recentemente para aumentar o engajamento e a conversão.

O que você vai aprender

Você vai conectar o Klaviyo Customer Hub a uma vitrine headless do Shopify, 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

• Uma vitrine headless da Shopify com acesso à API Storefront (token de acesso público/chave pública da API Storefront no Administrador Headless da Shopify).
• Seu ID da empresa Klaviyo (usado pelo carregador de JavaScript no site).
• Decisão sobre o login do comprador: Shopify Customer Account API ou Klaviyo One Time Password (OTP).
  • Se você estiver usando contas existentes, deixe prontas as rotas de Login, Logout e (opcional) Gerenciar conta e Gerenciar endereços da sua loja.
• Capacidade de editar o código da sua vitrine e implementar alterações.
• Uma função de conta com permissão para editar o Klaviyo Customer Hub, como Proprietário ou Administrador. Para uma função personalizada, inclua permissões de visualização e edição do Klaviyo Customer Hub.
• Uma avaliação do Klaviyo Customer Hub ou um plano que inclua Favoritos e FAQs, se você quiser usar esses recursos.

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 de compra úteis. Para Shopify headless, você conecta o script onsite da Klaviyo, escolhe um método de login (API de conta de cliente da Shopify ou Klaviyo OTP) e, opcionalmente, adiciona:

• Produto com atividade: mostra o produto que um consumidor está visualizando dentro do hub.
• Vistos recentemente: lista os produtos vistos recentemente usando o rastreamento da Klaviyo.
• Widgets de favoritos e FAQs: são exibidos nas páginas de detalhes do produto (PDPs) e dentro do Hub.

Use o Klaviyo Customer Hub quando você quiser uma camada de assistência na página que impulsione a descoberta de produtos e um checkout mais rápido, melhorando a conversão e o valor da vida útil.

Configuração

1. Configure as configurações do Klaviyo Customer Hub

Primeiro, siga Guia de introdução ao Klaviyo Customer Hub e conclua o assistente de integração. Mantenha o Klaviyo Customer Hub oculto até que sua configuração headless esteja pronta. Em seguida, acesse Klaviyo Customer Hub > Configurações e encontre Configuração headless da Shopify.

Ative a opção Configuração Headless do Shopify e cole seu token de acesso público do Shopify em Chave pública da API Storefront.

Em Login do comprador, selecione API de conta de cliente da Shopify para usar seu login existente da Shopify ou Senha de uso único (OTP) da Klaviyo para um login que funciona apenas com a Klaviyo.

Se você selecionar API de conta de cliente da Shopify, insira a rota de login e a rota de logout da sua loja. A rota de gerenciamento da conta e a rota de gerenciamento de endereços são opcionais. Essas rotas redirecionam os compradores entre o Hub e o seu site.

Se você selecionar Klaviyo One Time Password (OTP), insira Nome de exibição da loja e E-mail de resposta. O e-mail de resposta não pode usar um endereço gmail.com ou klaviyo.com.

Clique em Salvar para salvar suas configurações. Para conferir o status de publicação do Hub, clique em Abrir editor. Mantenha o status como Oculto até você concluir a configuração da vitrine e os testes abaixo.

2. Carregue o JavaScript do Klaviyo Customer Hub (instruções para desenvolvedores)

Dica: Se você já usa recursos onsite da Klaviyo, talvez já tenha um loader configurado. Confirme antes de adicionar um segundo script.

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

// customerHub.js
// TODO: Configuration
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);

No seu layout raiz (por exemplo, root.tsx), inclua o loader para que o script onsite carregue em todas as páginas. Procure pela mensagem no console “Klaviyo JS script loaded successfully.”

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

Depois que o Hub terminar de carregar, window.customerHubApi fica disponível. A mensagem de sucesso do carregador confirma que o script foi carregado; espere a API do Hub antes de chamar hydrateProduct, como mostrado abaixo.

3. Mostrar o produto com atividade no Klaviyo Customer Hub

Adicione o script a seguir ao HTML da sua página de produto, substituindo your-product-handle pelo identificador (handle) atual do produto no Shopify. Se a sua loja usa React ou outro framework com navegação no lado do cliente, execute a chamada de hidratação a partir do ciclo de vida da página desse framework sempre que o produto mudar.

<!-- Product page HTML -->
<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>

No desktop, o Hub pode exibir o card do produto atual na aba Chat quando o chat web está ativado. Esse card não é exibido no celular.

4. Ative produtos visualizados recentemente no Klaviyo Customer Hub

Implemente o rastreamento de Viewed Product nas páginas de produto para que você possa usar essa métrica na Klaviyo. Além disso, chame trackViewedItem para armazenar produtos visualizados recentemente no navegador do comprador para o Hub. Siga os exemplos de rastreamento em Integrar uma plataforma de e-commerce sem uma integração predefinida com a Klaviyo.

5. Ative o sequestro do link da conta

Quando o Klaviyo Customer Hub estiver AO VIVO, ele poderá substituir links de conta que terminam em /account ou /account/login para que eles abram o Hub. Para abrir o Hub a partir de um ícone de conta personalizado, defina o link como #k-hub. Adicione data-k-hub-ignore a um link de conta se ele deve continuar abrindo a página de conta da sua vitrine.

6. Conectar a autenticação da API de conta de cliente do Shopify (recomendado)

Conclua esta etapa apenas se você selecionou API de conta de cliente da Shopify em Login do cliente. Se você selecionou Senha de uso único (OTP) da Klaviyo, pule para a etapa 7.

Adicione uma rota de servidor em /api/authenticateCustomerHub que aceite solicitações POST e envie o token de acesso do cliente conectado para a Klaviyo. Defina COMPANY_ID no exemplo como o ID da sua empresa na Klaviyo.

O exemplo a seguir usa o framework Hydrogen da Shopify. Adapte a rota do servidor ao seu framework se você usar uma vitrine diferente.

// ./app/routes/api.authenticateCustomerHub.js
// TODO: Configuration
const COMPANY_ID = '';
export async function action({context}) {
  // Pull the Customer Account API Client from your storefront's context
  const {customerAccount} = context;
  try {
    // Get the access token for the current customer
    const accessToken = await customerAccount.getAccessToken();
    if (!accessToken) {
      return new Response(JSON.stringify({message: 'User not logged in'}), {
        status: 200,
      });
    }
    // Send the access token to the 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();
    // Return the actual response from Customer Hub with the same status code
    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 essa rota e as rotas da vitrine nas configurações do Klaviyo forem configuradas, o Klaviyo Customer Hub poderá se conectar ao login da sua conta de cliente existente.

7. Adicione o widget Favoritos (recomendado)

Favoritos e perguntas frequentes podem aparecer dentro da gaveta do Klaviyo Customer Hub. Você também pode adicioná-los às páginas de detalhes do produto para que os clientes possam salvar produtos e encontrar respostas enquanto navegam.

Primeiro, ative os Favoritos no editor do Hub. Em seguida, acesse Klaviyo Customer Hub > Design, selecione Favoritos e escolha quais compradores podem ver o widget no site. Clique em Publicar para salvar as configurações do widget e, em seguida, adicione o seguinte contêiner à sua página de produto. Substitua o ID de produto da Shopify no exemplo pelo ID do produto atual.

// products.tsx
// Example identifiers:
//   id: gid://shopify/Product/12345
//   data-product-id: 12345
const gid = "gid://shopify/Product/12345";
const productId = gid.split('/').pop();

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

Depois que o Klaviyo Customer Hub estiver ao vivo e o widget estiver visível para o shopper, ele pode clicar em Adicionar aos favoritos em uma página de produto. Os produtos salvos aparecem na experiência de Favoritos do Hub.

8. Adicione blocos de FAQ (recomendado)

Crie seus blocos de perguntas frequentes no Klaviyo. Em Klaviyo Customer Hub > Design, selecione FAQ, escolha as perguntas para exibir nas páginas de produtos e configure a visibilidade e o design no site. Clique em Publicar para salvar suas configurações antes de adicionar o contêiner abaixo.

Adicione este contêiner à sua página de produto com o ID do produto atual na Shopify. As mesmas perguntas frequentes selecionadas aparecem em todas as páginas de produto; o ID do produto não seleciona perguntas diferentes para cada produto.

// products.tsx
// Example:
const gid = "gid://shopify/Product/12345";
const productId = gid.split('/').pop();

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

Os botões de perguntas frequentes selecionados aparecem nas páginas de produtos de acordo com as suas configurações de visibilidade. Ao clicar em uma pergunta, a resposta é aberta no Klaviyo Customer Hub.

9. Teste e ative o Klaviyo Customer Hub

Teste o código da sua loja virtual em staging antes de fazer o deploy em produção. A tomada de controle automática de links de conta e o widget Favoritos no site exigem Live; por isso, inclua-os nas suas verificações finais no ambiente live.

1. Quando você estiver pronto para publicar, acesse Klaviyo Customer Hub > Configurações e clique em Abrir editor.
2. Salve todas as alterações de design pendentes do Hub. Em seguida, selecione Ao vivo no menu suspenso de status ou clique em Ativar quando o Hub estiver oculto e não houver alterações não salvas.
3. Aguarde a confirmação de que o Klaviyo Customer Hub está ativo. Na sua vitrine de produção, verifique o login e o logout, o ícone da conta, o card de produto do Chat no desktop (se estiver ativado), os produtos visualizados recentemente e quaisquer widgets de Favoritos ou de Perguntas frequentes que você adicionou.

Práticas recomendadas

• Publique em produção somente após testar, para ajudar a evitar problemas de suporte. Mantenha o Hub de produção Oculto até a configuração ficar pronta e, em seguida, defina-o como Ativo no editor do Hub.
• Hidrate o produto com atividade nas PDPs para manter o contexto do produto disponível no Hub e ajudar os clientes a adicioná-lo ao carrinho. Monitore a taxa de conversão e a receita por destinatário (taxa de recompra, RPR) para avaliar o efeito.
• Implemente o rastreamento de produtos logo no início para preencher os produtos vistos recentemente e dar suporte a fluxos baseados em navegação. Monitore o engajamento e a receita da recuperação de navegação.
• Adicione Favoritos para oferecer aos compradores uma forma fácil de salvar uma lista curta. Monitore visitas recorrentes e a atividade de adicionar ao carrinho.
• Use as perguntas frequentes para responder a dúvidas sobre envio, materiais ou devoluções enquanto os clientes navegam. Monitore a taxa de desistência e a taxa de conversão.
• Use a autenticação do lado do servidor com a Shopify Customer conta API quando disponível para manter a continuidade para compradores que fizeram login e ajudar a reduzir solicitações de suporte relacionadas ao login.

Medir o sucesso

Use Analytics > Métricas para monitorar a atividade de Viewed Product. Analise o desempenho nas etapas seguintes nos seus fluxos e campanhas. Use seus painéis de receita de e-commerce para acompanhar as mudanças na conversão e no valor médio de pedido (valor médio de pedido) depois de ativar o Klaviyo Customer Hub.

Acompanhe a taxa de conversão nas páginas de produto, a taxa de adição ao carrinho, as sessões com aberturas do Hub (se instrumentado), a receita por destinatário (receita por destinatário) e a receita gerada por navegação vinculada a eventos Viewed Product.

Verificações rápidas

• Para uma baixa atividade de itens visualizados recentemente, verifique o rastreamento de produtos e confirme se os eventos de Produto visualizado estão sendo atribuídos aos perfis. Verifique também o rastreamento de itens visualizados recentemente baseado no navegador.
• Para baixa atividade de adição ao carrinho no Hub, verifique se a hidratação de produto com atividade é executada em cada PDP e se as variantes e os preços estão corretos.
• Para poucas adições aos Favoritos, coloque o espaço de Favoritos perto das principais chamadas à ação da página do produto e confirme que data-product-id corresponde ao produto.

Solução de problemas

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

Causa provável: script não carregando ou Hub está Oculto.

Correção: confirme se o customerHub.js é carregado, se o ID da empresa está definido e se o Klaviyo Customer Hub está ao vivo. Para alterar o status, vá para Klaviyo Customer Hub > Configurações > Abrir editor e use o menu suspenso de status.

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

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

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

Sintoma: o card do produto com atividade não aparece no Hub em PDPs.

Causa provável: está faltando a chamada de hidratação, o identificador do produto está incorreto ou você está verificando o card de produto do Chat no celular.

Correção: no desktop, abra o Chat com o chat web ativado. Garanta que o loop de espera seja executado e chame window.customerHubApi.hydrateProduct("<handle>") com o identificador correto do produto.

Sintoma: a seção de vistos recentemente está vazia.

Causa provável: rastreamento de produtos ausente ou incompleto.

Correção: adicionar rastreamento do evento Viewed Product e rastreamento do navegador trackViewedItem. Verifique eventos em um perfil reconhecido e confira os produtos visualizados recentemente no mesmo navegador.

Sintoma: widgets de Favoritos ou FAQ não são renderizados na PDP.

Causa provável: falta de um contêiner, ID do produto incorreto, widget oculto ou um plano que não inclui o recurso.

Correção: Adicione <div class="kl-hub-favorites-slot" data-product-id="..."></div> ou <div class="klaviyo-faqs-slot" data-product-id="..."></div> com o ID de produto correto. Confirme o acesso e a visibilidade dos recursos no Klaviyo e selecione as perguntas frequentes para as páginas de produtos. O Klaviyo Customer Hub também precisa estar Ao vivo para o widget de Favoritos aparecer.

Sintoma: ao clicar no ícone da conta, o Hub não abre.

Causa provável: o link da conta não corresponde a um URL de conta compatível, está excluído da tomada de controle ou o Klaviyo Customer Hub está oculto.

Correção: defina o Klaviyo Customer Hub como Ativo, use um link de conta que termine em /account ou /account/login ou defina href="#k-hub". Remova data-k-hub-ignore apenas dos links que devem abrir o Hub.

Sintoma: Com a API de conta de cliente do Shopify selecionada, os compradores não são reconhecidos como conectados no Hub.

Causa provável: rota /api/authenticateCustomerHub ausente ou solicitação de API com falha.

Correção: Implemente o exemplo do Hydrogen (ou o equivalente no seu framework), envie access_token e company_id para o ponto de extremidade de login da Klaviyo e retorne a resposta.

Perguntas frequentes

P: Preciso usar a Shopify Customer Conta API para fazer login?

R: Não. Em vez disso, você pode usar a Senha de uso único (OTP) da Klaviyo. Se você já usa contas da Shopify, conecte-se pela API de conta de cliente da Shopify para ter uma experiência sem complicações.

P: Quais rotas da vitrine eu preciso fornecer?

R: Para a API de conta do cliente do Shopify, forneça a rota de login e a rota de logout. A rota de gerenciar conta e a rota de gerenciar endereços são opcionais para links mais aprofundados.

P: Onde encontro a chave pública da API da vitrine?

A: Use o token de acesso público da sua vitrine no canal Headless do Shopify. Siga o guia de configuração da Storefront API do Shopify e, em seguida, insira o token público no campo Chave pública da Storefront API do Klaviyo.

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

R: Sim. Quando o Klaviyo Customer Hub estiver ao vivo, links que terminam em /account ou /account/login podem abrir o Hub automaticamente. Você também pode apontar o link da sua conta para #k-hub.

P: O Shopify Hydrogen é obrigatório?

A: Não. O exemplo de autenticação usa o Hydrogen, mas qualquer framework pode implementar uma rota de servidor em /api/authenticateCustomerHub que faça POST do token de acesso e do company_id para a Klaviyo.

P: Favoritos e Perguntas frequentes podem ficar em PDPs e dentro do Hub?

R: Sim. Configure Favoritos e Perguntas frequentes no Klaviyo e, em seguida, adicione as divs de contêiner delas às páginas do seu produto. A visibilidade delas no Hub e nas páginas do produto segue as configurações que você escolher.