Identificando usuários

O Kilden separa eventos (imutáveis) de pessoas (mutáveis). Todo evento carrega um distinct_id; a resolução de identidade mapeia distinct ids para pessoas, de modo que a atividade antes e depois do cadastro pertença ao mesmo ser humano.

Anônimo por padrão

Na primeira visita, o SDK gera um id anônimo — anon_ + UUID v7 —, persiste esse id e o carimba em cada evento. Uma pessoa é criada para ele no primeiro evento. Nenhuma chamada é necessária.

Quando você sabe quem é o usuário, chame identify com o seu id de usuário estável (um id de banco de dados funciona melhor que um email — emails mudam):

kilden.identify('user_4821', { email: '[email protected]', plan: 'pro' });

Isso emite um evento $identify que carrega os dois ids (o id de usuário como distinct_id, o id anônimo como $anon_distinct_id). O pipeline então faz uma de duas coisas:

Seu id de usuário é novo (o caso comum, ~90%): ele é adicionado como mais um distinct id da pessoa do visitante anônimo. Todo o histórico pré-cadastro já está atribuído — nada se move.
Seu id de usuário já tem uma pessoa (login em um segundo dispositivo): as duas pessoas fazem merge.

Chame identify em toda página em que o usuário estiver logado, não só no login — a chamada é idempotente, e é isso que mantém dispositivos novos e navegadores com dados limpos vinculados.

O que um merge faz

A pessoa mais antiga vence (pelo seu created_at); os distinct ids da pessoa mais nova são reapontados para ela.
Traits: em caso de conflito, a vencedora mantém seus valores; a perdedora só preenche lacunas. Um $set posterior sobrescreve de qualquer forma.
Eventos passados continuam funcionando nas queries: merges de pessoas são resolvidos em tempo de consulta, então eventos históricos atribuídos à pessoa perdedora contam para a vencedora.

Atualizando traits

kilden.setPersonProperties(
  { plan: 'enterprise' },       // $set — sobrescreve
  { signup_source: 'organic' }, // $set_once — só se ainda não existir
);

Traits vivem na pessoa e podem mudar; eventos são congelados no momento da captura. Se você precisa que um valor seja confiável (plano de cobrança, receita), envie-o server-side com uma secret key ou como traits assinados — tudo o que um navegador envia pode ser forjado pelo dono do navegador.

reset() no logout

kilden.reset();

Rotaciona o id anônimo e limpa o token de identidade e as super properties. Pule esse passo e a próxima pessoa a fazer login naquele navegador será vinculada ao rastro anônimo do usuário anterior.

Regras que protegem você

Dois ids conhecidos nunca fazem merge automaticamente. Se um usuário identificado for de alguma forma identificado como um id conhecido diferente, o Kilden recusa o merge (é quase sempre um bug de instrumentação), registra o caso e atribui o evento à pessoa do id de usuário. O SDK web deliberadamente não tem alias() — identify cobre o fluxo do navegador por completo; $alias existe no pipeline para SDKs de servidor, onde vincular dois ids conhecidos é legítimo.
O limite de distinct ids por pessoa (100 por padrão) evita o acúmulo descontrolado de ids (“person bloat”); acima do limite, os eventos ainda são atribuídos, mas novos mapeamentos não são criados.
Com a verificação de identidade em modo enforce, um identify não verificado vindo de um navegador não pode criar nem modificar mapeamentos de identidade.