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

1. 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).
2. Seu ID da empresa Klaviyo (usado pelo carregador de JavaScript no site).
3. Decisão sobre o login do comprador: Shopify Customer Account API ou Klaviyo One Time Password (OTP).
   1. Se você estiver usando contas existentes, deixe prontas as rotas de Login, Logout e (opcional) Gerenciar conta e Gerenciar endereços da sua loja.
4. Capacidade de editar o código da sua vitrine e implementar alterações.
5. Quem pode configurar isso: Você precisa de uma função de conta que permita editar as configurações do Klaviyo Customer Hub e publicar widget (Proprietário, Administrador ou uma função personalizada que tenha acesso de gravação a Conteúdo e chave de API).

Visão geral

O Klaviyo Customer Hub é uma sobreposição em todo o site que dá aos compradores acesso mais rápido a ações da conta e ferramentas de compras úteis. Para Shopify headless, você conecta o script no site da Klaviyo, escolhe um método de login (API de Contas de Cliente ou OTP da Klaviyo) e, opcionalmente, adiciona:

1. Produto com atividade: mostra o produto que um consumidor está visualizando dentro do hub.
2. Vistos recentemente: lista os produtos vistos recentemente usando o rastreamento da Klaviyo.
3. Widgets de favoritos e perguntas frequentes: renderizam em 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 - Defina as configurações do Klaviyo Customer Hub

Primeiro, siga Guia de introdução ao Klaviyo Customer Hub e conclua o assistente de integração, como em qualquer outra configuração. Depois que isso for concluído, acesse Klaviyo Customer Hub > Configurações. Você verá a seção de Configuração sem referência à Shopify.

Ative a configuração de Shopify headless e depois cole sua chave pública da API da Storefront do Administrador Headless da Shopify (token de acesso público).

Em Login do comprador, selecione a API de conta de cliente do Shopify (recomendado para que todos os apps da sua loja possam compartilhar o login do Shopify) ou a Senha de uso único (OTP) do Klaviyo (funciona apenas com o Klaviyo e não fará login de compradores em nenhum outro app).

Se você selecionar Shopify Customer Account API, insira também as rotas de Login, Logout e, opcionalmente, Gerenciar conta/Gerenciar endereços da sua vitrine (usadas para redirecionamentos entre o Hub e seu site).

Visibilidade de publicação: defina o Klaviyo Customer Hub como Ao vivo.

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);

O script no site é carregado em todas as páginas. Procure a mensagem no console: “O script JS da Klaviyo foi carregado com sucesso.”  No seu layout raiz (por exemplo, root.tsx), inclua o loader:

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

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

3 - Mostrar o produto com atividade no Klaviyo Customer Hub

Adicione a chamada de hidratação na 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>

Agora, o Hub deve exibir um card de produto adicional para a PDP que o comprador está visualizando na guia "Chat", se você tiver essa opção ativada.

4 - Ativar produtos vistos recentemente no Klaviyo Customer Hub

Implemente o rastreamento de Produto visualizado para que o Hub possa preencher 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 estão disponíveis aqui na nossa documentação do Klaviyo Developers: Integrar uma plataforma de e-commerce sem uma integração do Klaviyo pré-criada.

5 - Ativar a tomada de controle do link da conta

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

6 - Configure o Klaviyo Customer Hub com autenticação da API Customer Accounts (recomendado)

Para usar as contas de cliente e a configuração de autenticação da sua vitrine atual, o Klaviyo Customer Hub exigirá que você adicione uma nova rota de API à sua vitrine, que lidará com a transmissão segura do token de acesso de um cliente conectado aos nossos serviços. O importante é que a nova rota da API tenha um nome e possa ser acessada com '/api/authenticateCustomerHub'.

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

// ./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 isso for configurado, bem como as rotas da loja virtual definidas nas configurações do Klaviyo, o Klaviyo Customer Hub poderá se conectar à sua configuração de autenticação existente e oferecer um ponto de entrada perfeito para as contas de clientes existentes.

7 - Adicionar o widget de Favoritos (recomendado)

Tanto Favoritos quanto Perguntas frequentes funcionarão dentro do painel do Klaviyo Customer Hub. No entanto, você também pode adicionar esses widgets em PDPs para aumentar o engajamento.

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

// 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}
  />
)

Agora, os compradores podem clicar em Adicionar aos favoritos nas PDPs; o item aparece em Itens favoritos no Hub.

8 - Adicionar blocos de perguntas frequentes (recomendado)

Assim como ao adicionar Favoritos, adicionar blocos de FAQ é tão simples quanto adicionar uma div na sua página de produto com o ID do produto incluído, para renderizar FAQs que você pode editar e personalizar no Klaviyo.

Adicione um bloco de perguntas frequentes específico do produto que você criar na Klaviyo:

// 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 chips/botões de FAQ agora devem aparecer em PDPs, se estiverem configurados, e podem ser editados na Klaviyo

Práticas recomendadas

1. Publique em produção somente após a verificação — mantenha o ambiente de staging oculto até a garantia de qualidade (QA) ser concluída; depois, defina Ao vivo para expor o Hub. Impacto: menos problemas de suporte, tempo de retorno mais rápido.
2. Sempre hidrate o Produto com atividade em PDPs — mantém o contexto do produto visível no Hub e incentiva a ação de adicionar ao carrinho. Impacto: taxa de conversão, taxa de recompra.
3. Implemente o rastreamento de produto visualizado logo no início — preenche a seção Vistos recentemente e libera fluxos baseados em navegação. Impacto: engajamento e receita com recuperação de navegação.
4. Adicionar aos favoritos — cria uma ação de salvar com pouco atrito e uma lista curta persistente. Impacto: visitas repetidas, adicionar ao carrinho.
5. Use FAQs para lidar com objeções — responda perguntas sobre frete, materiais ou devoluções no próprio texto para reduzir o abandono. Impacto: taxa de conversão.
6. Prefira a autenticação do lado do servidor com a API de Contas de Cliente quando disponível — melhora a continuidade para clientes conectados. Impacto: qualidade da experiência, deflexão de suporte. 

Medir o sucesso

Onde ver os resultados: use Análise > Métricas para monitorar a atividade de Produto visualizado e o desempenho dos fluxos/campanhas associados. Use seus painéis de receita de e-commerce para acompanhar mudanças na conversão e no valor médio de pedido depois de ativar o Klaviyo Customer Hub. Principais métricas para acompanhar: taxa de conversão da PDP, taxa de adição ao carrinho, sessões com aberturas do Hub (se instrumentado), receita por destinatário (receita por destinatário) e receita gerada por navegação vinculada a eventos de Produto visualizado. Checklist de correções rápidas: Pouca atividade de Visualizados recentemente? Verifique se o snippet de rastreamento de Produto visualizado está disparando e se os eventos são atribuídos a perfis. Poucas adições ao carrinho pelo Hub? Verifique se a hidratação de Produto com atividade é executada em todas as PDPs e se variantes/preços estão corretos. Poucas adições aos Favoritos? Mova o slot de Favoritos para perto dos principais CTAs da PDP e confirme se o 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 carrega (verifique o console), se o ID da empresa está definido e se a visibilidade do Klaviyo Customer Hub está como Ao vivo em Klaviyo Customer Hub > Configurações.

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: hydrateProduct não foi chamado ou o identificador do produto está incorreto.

Correção: 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 Viewed Product não implementado.

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

Sintoma: widgets de Favoritos ou FAQ não são renderizados na 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 do produto correto.

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

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

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

Sintoma: Os compradores não são reconhecidos como conectados dentro do 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: Eu preciso usar a API de Contas de clientes do Shopify para login?

A: 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 contas de cliente para ter uma experiência integrada.

P: Quais rotas da vitrine eu preciso fornecer?

A: Se estiver usando suas conta existentes, forneça rotas de Login e Logout; Gerenciar conta e Gerenciar endereços são opcionais para um link mais profundo.

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

A: No Administrador Headless do Shopify, em Storefront API > Token de acesso público (também chamado de chave pública da Storefront API).

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

A: Sim. Se o link da sua conta no cabeçalho usar /account, o Klaviyo Customer Hub pode abrir automaticamente; você também pode direcioná-lo 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?

A: Sim. Adicione as divs de contêiner correspondentes nas PDPs; elas também aparecerão na gaveta do Hub.