Identificar usuarios

Kilden separa los eventos (inmutables) de las personas (mutables). Cada evento lleva un distinct_id; la resolución de identidad mapea distinct ids a personas para que la actividad previa y posterior al registro pertenezcan al mismo humano.

Anónimo por defecto

En la primera visita el SDK genera un id anónimo — anon_ + UUID v7 —, lo persiste y lo estampa en cada evento. En el primer evento se crea una persona para él. No hace falta ninguna llamada.

Cuando sabes quién es el usuario, llama a identify con tu id de usuario estable (un id de base de datos funciona mejor que un email — los emails cambian):

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

Esto emite un evento $identify que lleva ambos ids (el id de usuario como distinct_id, el id anónimo como $anon_distinct_id). El pipeline entonces hace una de dos cosas:

Tu id de usuario es nuevo (el caso común, ~90%): se agrega como otro distinct id de la persona del visitante anónimo. Todo el historial previo al registro ya está atribuido — nada se mueve.
Tu id de usuario ya tiene una persona (login en un segundo dispositivo): las dos personas se fusionan (merge).

Llama a identify en cada página donde el usuario esté logueado, no solo en el login — es idempotente, y es lo que mantiene enlazados los dispositivos nuevos y los navegadores con datos borrados.

Qué hace un merge

Gana la persona más antigua (por su created_at); los distinct ids de la más nueva se re-apuntan a ella.
Traits: la ganadora conserva sus valores en caso de conflicto; la perdedora solo rellena huecos. Un $set posterior sobreescribe en cualquier caso.
Los eventos pasados siguen funcionando en las queries: los merges de personas se resuelven en tiempo de consulta, así que los eventos históricos atribuidos a la persona perdedora cuentan para la ganadora.

Actualizar traits

kilden.setPersonProperties(
  { plan: 'enterprise' },       // $set — sobreescribe
  { signup_source: 'organic' }, // $set_once — solo si no existe
);

Los traits viven en la persona y pueden cambiar; los eventos quedan congelados al momento de la captura. Si necesitas que un valor sea confiable (plan de facturación, revenue), envíalo server-side con una secret key o como traits firmados — cualquier cosa que envíe un navegador puede ser falsificada por el dueño de ese navegador.

reset() en logout

kilden.reset();

Rota el id anónimo, limpia el token de identidad y las super properties. Si te lo saltas, la siguiente persona que inicie sesión en ese navegador queda enlazada al rastro anónimo del usuario anterior.

Reglas que te protegen

Dos ids conocidos nunca se fusionan automáticamente. Si un usuario identificado de alguna forma se identifica como un id conocido distinto, Kilden rechaza el merge (casi siempre es un bug de instrumentación), lo registra en logs, y atribuye el evento a la persona del id de usuario. El SDK web deliberadamente no tiene alias() — identify cubre el flujo del navegador por completo; $alias existe en el pipeline para SDKs de servidor, donde enlazar dos ids conocidos es legítimo.
Tope de distinct ids por persona (100 por defecto) evita la acumulación descontrolada de ids (“person bloat”); superado el tope, los eventos se siguen atribuyendo pero no se crean mapeos nuevos.
Con la verificación de identidad en modo enforce, un identify no verificado desde un navegador no puede crear ni modificar mapeos de identidad en absoluto.