Rastreamento de links no Klaviyo: cliques em links curtos como métrica personalizada

O rastreamento de links do Klaviyo pelo Elido é feito no servidor e funciona em uma só direção: cada clique em um dos seus links curtos é enviado para a Events API do Klaviyo como um evento em uma métrica personalizada chamada Elido Link Click. O evento traz o slug e o ID do link, o país e o dispositivo, o destino para o qual o visitante foi enviado e o horário do clique. A métrica é criada no primeiro uso, e você pode gerar gráficos, filtrá-la e criar relatórios com ela como faria com qualquer outra.

O que ele não faz é colocar o clique no perfil de um assinante. Cada evento é associado ao link por meio de um ID anônimo, portanto um link clicado por 4.000 pessoas aparece no Klaviyo como um perfil anônimo com 4.000 eventos na linha do tempo. Esse único fato define para que a integração serve. Vou explicar o payload, a configuração, o que fluxos e segmentos podem fazer com ele e como ele se compara ao rastreamento nativo de cliques do Klaviyo.

Se os seus links ainda não têm tags consistentes, corrija isso primeiro. O artigo principal sobre rastreamento de UTMs de ponta a ponta explica a convenção, e o Klaviyo só enxerga o que o link carrega.

O que o Elido envia ao Klaviyo a cada clique

Um clique, um POST. O forwarder chama https://a.klaviyo.com/api/events/ com sua chave privada no cabeçalho Authorization: Klaviyo-API-Key e um cabeçalho revision: 2023-02-22. Esse é o endpoint documentado na referência Create Event do Klaviyo.

Este é o corpo completo, com valores de exemplo:

{
  "data": {
    "type": "event",
    "attributes": {
      "time": "2026-09-21T09:14:22Z",
      "properties": {
        "workspace_id": 12,
        "link_id": 4711,
        "slug": "autumn-drop",
        "country": "DE",
        "device": "mobile",
        "destination": "https://shop.example/autumn?utm_source=instagram",
        "ip": "203.0.113.24"
      },
      "metric": {
        "data": {
          "type": "metric",
          "attributes": { "name": "Elido Link Click" }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "attributes": { "anonymous_id": "elido-link-4711" }
        }
      }
    }
  }
}

É tudo. Não há e-mail, número de telefone, campos de UTM como propriedades separadas, referrer nem navegador.

Alguns detalhes importam quando você começa a filtrar. destination é o URL que este visitante realmente recebeu, depois de quaisquer regras de roteamento de smart link, portanto um link que envia iPhones para a App Store e todas as outras pessoas para a sua loja produz dois valores de destino. device é um de mobile, tablet ou desktop. As tags UTM só existem dentro da string destination, portanto não é possível filtrar diretamente por utm_campaign; filtre por slug, que normalmente é uma chave mais limpa de qualquer forma.

Rastreadores que se identificam no user agent são descartados no redirecionamento e nunca são encaminhados. Cliques que as heurísticas do próprio Elido sinalizam como suspeitos ainda são enviados, e o evento não tem uma propriedade que indique isso.

Um perfil anônimo por link, e por quê

Todo evento do Klaviyo precisa indicar um perfil, identificado por um e-mail, número de telefone, ID externo, ID do Klaviyo ou um anonymous_id. O Elido sempre envia o último, construído como elido-link- mais o ID do link.

Assim, todo clique em autumn-drop vai para o mesmo perfil. O primeiro clique o cria, e cada clique posterior é acrescentado à linha do tempo.

Isso tem três consequências, e a terceira me surpreendeu.

Primeiro, as contagens funcionam, mas as pessoas são desconhecidas. Cliques totais, cliques por link, país e dispositivo funcionam. Qualquer coisa "única" contabiliza links, não pessoas.

Segundo, o perfil anônimo não tem e-mail nem telefone. Ele pode fazer parte de um segmento, mas não pode receber uma mensagem.

Terceiro, cliques no mesmo segundo são agrupados. O forwarder não envia unique_id, e a referência do Klaviyo diz que, sem ele, a deduplicação usa o horário do evento até o segundo, para o mesmo perfil e a mesma métrica. Como o perfil é por link, duas pessoas clicando no mesmo link dentro do mesmo segundo se tornam um único evento. Em um link de newsletter que chega aos poucos, você nunca perceberá. Em um link de um story grande no Instagram, em que os cliques chegam vários por segundo no pico, a contagem do Klaviyo ficará abaixo da contagem nas suas análises de cliques do Elido. A vantagem: a única nova tentativa do forwarder não gera contagem duplicada, porque um evento reenviado tem o mesmo horário.

Por que não usar um ID por visitante? O redirecionamento não sabe quem é o visitante, e eu prefiro que ele não deixe um cookie em um domínio que o visitante nunca escolheu visitar. É a mesma troca que fizemos no rastreamento de links do Mixpanel, em que distinct_id é por link pelo mesmo motivo.

Configurando o rastreamento de links do Klaviyo no Elido

A configuração tem um campo.

1. No Klaviyo, acesse Settings, depois API keys, e crie uma chave de API privada. A referência Create Event lista events:write como o escopo necessário. As notas de configuração no aplicativo do Elido também mencionam profiles:write; eu começaria apenas com events e adicionaria o segundo se o Klaviyo retornar 403.
2. No seu workspace do Elido, abra Integrations, escolha o cartão do Klaviyo e clique em Connect Klaviyo.
3. Cole a chave em Private API Key e salve. O Elido a criptografa em repouso e depois só a exibe mascarada.
4. Aguarde cerca de cinco minutos. As configurações da integração ficam armazenadas em cache no lado do encaminhamento, portanto os primeiros cliques depois de salvar podem não ser enviados.
5. Clique em um dos seus links pelo celular, abra Analytics > Metrics no Klaviyo e procure Elido Link Click.

O botão Test connection envia um evento de teste (marcado como elido_test: true) ao Klaviyo e mostra a resposta do Klaviyo, portanto uma chave revogada ou somente leitura falha imediatamente. Isso prova que a chave funciona, não que a métrica chega ao perfil esperado. A aparição da métrica no Klaviyo depois de um clique real é a prova.

Não há uma chave por link. Cada clique no workspace é encaminhado, inclusive links que você nunca pretendeu usar em marketing. Agências que trabalham com muitos clientes devem dar a cada cliente seu próprio workspace antes de conectar qualquer coisa.

Rastreamento nativo de cliques do Klaviyo versus a métrica do Elido

O Klaviyo já rastreia cliques nos próprios e-mails e mensagens de texto, e para trabalhos no nível do assinante esse rastreamento nativo vence. Ele reescreve cada link pelo próprio domínio de rastreamento, registra Clicked Email ou Clicked SMS no perfil do destinatário e marca possíveis rastreadores com uma propriedade Bot Click que você pode excluir dos relatórios.

O lugar da métrica do Elido é em todos os outros casos: o link na bio do Instagram, um código QR na embalagem, um link que um parceiro envia na própria newsletter, um link nas notas de um podcast. Nenhum desses cliques passa pelo rastreador do Klaviyo. Com o forwarder ativado, eles aparecem na mesma conta que as métricas de e-mail, portanto um dashboard do Klaviyo pode colocar "clicou no link de outono de qualquer lugar" ao lado de "clicou no e-mail de outono".

Observe uma interação. Em e-mails ativos, o Klaviyo acrescenta um parâmetro _kx a cada link para que o script no site possa identificar quem clicou no seu site. Se o link do seu e-mail for um link curto do Elido, _kx chega ao URL curto, e o redirecionamento do Elido não leva parâmetros de consulta recebidos para o destino. A identificação no site é perdida. Minha regra: dentro dos e-mails do Klaviyo, crie links diretamente para o seu próprio site e deixe o Klaviyo rastreá-los; use links curtos nos canais que o Klaviyo não consegue alcançar.

Levando cliques a perfis reais de assinantes

Às vezes você quer mesmo associar o clique a uma pessoa. Há duas maneiras que funcionam hoje, e nenhuma delas é o forwarder.

A mais fácil é deixar o rastreamento no site do Klaviyo cuidar da identidade. Envie o link curto compartilhado para um destino com tags UTM e garanta que o JavaScript do Klaviyo seja executado nessa página. Visitantes que já têm um cookie de um clique anterior em um e-mail, ou que se cadastram por um formulário, têm a atividade no site associada ao perfil. O clique no link curto continua anônimo; a visita posterior, não. Você então compara os dois no nível da campanha, que é mais amplo que o nível individual, mas é honesto sobre o que cada lado sabe.

A opção mais trabalhosa são os links por destinatário. Para uma lista pequena e de alto valor, como uma sequência B2B ou convites VIP, crie um link curto por pessoa pela API em /v1/workspaces/{workspace_id}/links e mantenha sua própria tabela relacionando o ID do link ao e-mail. Inscreva-se nos eventos de link por webhooks, procure o e-mail quando chegar um clique e envie seu próprio evento ao Klaviyo com esse e-mail como identificador do perfil. São talvez quarenta linhas de código, e esse é o único caminho que coloca um clique do Elido em um assinante identificado. Eu não faria isso para uma newsletter com 200.000 pessoas.

Se o que estava faltando eram contagens de cliques de vários canais dentro do Klaviyo, escolha um plano e conecte um workspace, depois direcione sua próxima campanha social por links de marca.

Limites do forwarder hoje

Cinco coisas que você precisa saber antes de basear um relatório nele.

A entrega é feita da melhor maneira possível. Um POST com falha sofre uma nova tentativa depois de um segundo e então é descartado; nada fica em fila para depois.

A Events API tem limite de taxa por conta, de 350 solicitações por segundo em picos e 3.500 por minuto de forma contínua. Esse orçamento é compartilhado com todos os outros aplicativos que escrevem eventos na sua conta. Um pico de campanha acima de aproximadamente 58 cliques por segundo, mantido por um minuto, encontrará respostas 429 e, depois da única nova tentativa, esses cliques desaparecerão do Klaviyo.

O cabeçalho de revisão é antigo. O Klaviyo dá dois anos a cada revisão da API antes da aposentadoria, e as solicitações para uma revisão aposentada são atendidas pela próxima mais antiga disponível. A revisão 2023-02-22 já passou desse limite, portanto hoje o forwarder funciona por fallback para uma revisão posterior. Funciona. Mesmo assim, eu gostaria que o cabeçalho fosse atualizado.

O IP do visitante é enviado como uma propriedade do evento. Espere que ele seja armazenado como qualquer outra propriedade, portanto trate-o como dado pessoal nos seus registros de tratamento. O guia de residência de dados na UE para equipes de marketing explica como avaliar isso.

Apenas cliques. Conversões não fazem parte do payload, portanto acompanhe a receita onde a identidade do cliente está, o que, para a maioria das lojas, é a própria integração de e-commerce do Klaviyo.

Relacionado no blog

• Rastreie UTMs de ponta a ponta - a convenção de tags da qual depende a união no nível da campanha.
• Rastreamento de links no Mixpanel - o mesmo padrão de forwarder, com a mesma identidade por link.
• Webhooks para eventos de links - o componente básico para eventos de cliques por destinatário.
• Atribuição de cliques em e-mails para Mailchimp, Brevo e Klaviyo - uma visão mais ampla entre plataformas de e-mail.
• Cliques em links curtos versus sessões do GA4 - por que contagens de cliques e sessões de análise nunca coincidem.
• Monitoramento de URLs no Datadog - o mesmo forwarder de cliques alimentando um dashboard do Datadog.