Holdy
Documentação/SDK Web

SDK Web

O SDK web (@holdy/sdk/web) instrumenta o browser. Ele gerencia sessão anônima, fila com flush em batch e retry — nenhum método público lança exceção, então telemetria nunca derruba o seu app.

Instalação e setup

npm install @holdy/sdk
import { initHoldy } from '@holdy/sdk/web'

const holdy = initHoldy({ apiKey: 'hol_live_...' })

Métodos

track(event, properties?)

Registra um evento. O nome é livre — use o vocabulário do seu produto.

holdy.track('invite_sent', { plan: 'pro' })

identify(userId, traits?)

Liga a sessão a um usuário do seu produto. O userId persiste para os próximos eventos da sessão, e o histórico anônimo anterior é fundido ao usuário no identity graph da Holdy.

holdy.identify('user_42', { role: 'admin' })

group(accountKey, traits?)

Associa a sessão a uma conta (empresa, workspace, organização). Use a chave que o seu produto conhece — a Holdy resolve para a conta interna.

holdy.group('acme-inc', { plan: 'scale' })

page(name?)

Registra uma visualização de página.

holdy.page('pricing')

Como o SDK se comporta

  • Sessão anônima — um anonymous_id é gerado e persistido em localStorage (holdy_anon_id) e acompanha todo evento até o identify.
  • Batching — eventos entram numa fila em memória com flush automático (20 eventos ou 5 segundos, o que vier primeiro) para POST /api/v1/events/bulk, em batches de até 500. No unload da página, o que restar na fila é enviado via sendBeacon.
  • Retry seguro — erros de rede e 5xx re-enfileiram o batch; o servidor deduplica e aceita parcialmente, então reenvio nunca duplica dados. Erros 4xx descartam o batch.