Sessões e identidade

A API de Analytics rastreia visitantes em dois eixos: anônimo (anonymousId) e autenticado (userId), conectados por sessões (sessionId).

anonymousId

Identificador estável que você gera no primeiro contato com o visitante (ex.: na primeira visita ao site) e persiste no localStorage ou cookie. Ele acompanha o visitante mesmo antes de qualquer login.

• Formato: string qualquer (UUID v4 é a convenção)
• Obrigatório em /track e /identify/public
• Persistência: você é responsável por mantê-lo. O script gtm.js salva em localStorage.crm_anonymous_id.

sessionId

Identificador da sessão atual (timeout de 30 minutos de inatividade). É opcional — quando você não envia, o nós resolvemos automaticamente uma sessão para o anonymousId:

• Se houver sessão ativa (último evento há menos de 30 min) → reutiliza.
• Caso contrário → cria uma nova sessão.

A resposta de /track e /identify/public retorna o sessionId resolvido em response.session.sessionId. Você pode persistir esse valor (ex.: localStorage.crm_session_id) e enviá-lo em eventos subsequentes para garantir que pertençam à mesma sessão.

userId

Identificador do usuário autenticado (o ID do seu sistema). Você o define quando o visitante faz login ou se cadastra, chamando /identify/public:

{
  "anonymousId": "anon-7c1f3a",
  "userId": "user-9182",
  "traits": { "email": "ana@exemplo.com" }
}

A partir dessa chamada, é persistido um mapeamento anonymousId → userId. Eventos futuros que não enviarem userId são automaticamente resolvidos via esse mapeamento (usando o anonymousId).

Fluxo típico

1. Primeira visita
   └─► gere anonymousId, salve em localStorage
   └─► envie /track com anonymousId
       └─► resposta inclui sessionId; salve em localStorage

2. Navegação na mesma sessão
   └─► envie /track com anonymousId (e sessionId, opcional)

3. Login
   └─► envie /identify/public com anonymousId + userId
       └─► sistema vincula anonymousId ↔ userId

4. Eventos pós-login
   └─► envie /track com anonymousId (userId é resolvido automaticamente)
       OU envie /track com userId explícito

Boas práticas

• Nunca troque o anonymousId durante a sessão. Persista-o entre páginas e visitas.
• Faça /identify/public o quanto antes após login/signup — isso enriquece a atribuição.
• Reuse o sessionId retornado pelo primeiro /track em chamadas subsequentes para evitar criar sessões fragmentadas.