Tracking entre subdomínios

Seu site de marketing vive em example.com, seu app em app.example.com. localStorage é por origin: se a identidade vivesse só ali, o visitante que leu sua página de preços e o visitante que se cadastra no seu app receberiam dois ids anônimos diferentes, e o histórico anterior ao cadastro — com a campanha que o trouxe — morreria na fronteira antes que o identify() tivesse chance de conectá-lo.

Já funciona sozinho

A persistência padrão é 'localStorage+cookie' com cookieDomain: 'auto', então o snippet puro cruza subdomínios com zero configuração:

kilden.init('YOUR_WRITE_KEY');

O pacote de identidade vive em um cookie first-party com escopo no domínio registrável — o único storage que todos os subdomínios conseguem ler —, espelhado no localStorage. Instale o snippet em ambos os sites com a mesma write key e o visitante mantém o mesmo id anônimo ao cruzar; o identify() no cadastro conecta todo o histórico de navegação anterior ao novo usuário.

O que vive no cookie

Só identidade: o id anônimo, o distinct id, a sessão, o estado de opt-out e o registro de first touch (abaixo). Super properties, caches e filas ficam no localStorage — cookies viajam no header de cada request ao seu domínio, então no cookie só entra o que precisa sobreviver à travessia.

Fixando explicitamente, ou desativando

cookieDomain: 'auto' testa domínios candidatos do mais amplo ao mais estreito e fica com o primeiro que o navegador aceita. Sufixos públicos (io, co.uk) quicam no cookie jar, então o auto aterrissa no domínio registrável (eTLD+1): em app.example.co.uk o cookie fica com escopo .example.co.uk. Hosts sem domínio (localhost, IPs) recebem um cookie host-only.

Se você prefere não depender da detecção em produção, fixe o escopo — é uma suposição a menos:

kilden.init('YOUR_WRITE_KEY', {
  cookieDomain: '.example.com',
});

Se o navegador rejeita o escopo pedido (um domínio que não bate com o host, um sufixo público), o SDK não funciona pela metade com um cookie que nunca gruda — ele recua para o comportamento de localStorage puro.

E para desativar cookies por completo:

kilden.init('YOUR_WRITE_KEY', {
  persistence: 'localStorage',
});

Isso mantém tudo no localStorage por origin — nenhum cookie é escrito nunca, e a identidade deixa de cruzar subdomínios.

Cookies e consentimento

O padrão escreve um cookie first-party. Se o seu setup precisa ficar livre de cookies, desative com persistence: 'localStorage' — mas não assuma que isso por si só encerra a questão de compliance: regulações como as regras de ePrivacy da UE são em geral tecnologicamente neutras, e armazenar informações no dispositivo do visitante pode exigir consentimento independentemente do mecanismo, então consulte sua própria orientação de privacidade sobre o que se aplica a você. O que muda de fato com cookies é que os scanners de consentimento os detectam — espere que o cookie do Kilden apareça em auditorias automatizadas, e garanta que seu banner de consentimento o declare.

Migração: visitantes existentes mantêm seu histórico

O padrão é seguro para sites com tráfego existente:

• Adoção em vez de frescor. Uma identidade pré-existente no localStorage é adotada para dentro do cookie, não substituída — visitantes existentes mantêm seu id e seu histórico em vez de bifurcar em um estranho.
• O cookie vence a divergência. Quando dois subdomínios tinham ids pré-existentes diferentes, a primeira página a carregar escreve o cookie compartilhado e a outra entra na linha — determinístico, sem briga. Os eventos já enviados sob o outro id continuam atribuídos a ele; se esse visitante se identificar, a resolução de identidade une os rastros.

Atribuição first-touch

Ligada por padrão, sem configuração. O SDK congela como traits da pessoa dois fatos com vidas diferentes:

• Como chegaram pela primeira vez — escrito na primeiríssima visita, mesmo uma direta: $initial_referrer ($direct quando não há), $initial_referring_domain, $initial_landing_page.
• Qual campanha os alcançou primeiro — $initial_utm_source, $initial_utm_medium, $initial_utm_campaign, $initial_utm_term, $initial_utm_content, escritos na primeira vez em que um parâmetro utm_* algum dia aparece, o que pode ser visitas depois.

Uma primeira visita direta não trava os campos de campanha em nada — uma diferença deliberada em relação ao PostHog, que congela os dois na visita um. Assim as duas perguntas são respondidas em vez de uma.

Tudo viaja como $set_once, que o pipeline aplica por chave: o tardio nunca sobrescreve o cedo, e reenviar é inofensivo. As properties de contexto $utm_* por evento não mudam — cada evento continua carregando a campanha da sua própria visita (veja Eventos e properties).

O registro de first touch faz parte do pacote de identidade, então com a persistência padrão o site de marketing e o app concordam sobre o que já foi registrado — a campanha capturada em example.com não é congelada de novo, diferente, em app.example.com.

Referência

As duas opções estão documentadas na referência de configuração do SDK.