SDK Web

Instrumente o front-end com @holdyapp/sdk: track, identify, group e page, com sessão anônima, batching e retry gerenciados pelo SDK.

O SDK web (@holdyapp/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

Por script tag, sem build:

<script src="https://holdy.chat/sdk/v1/holdy.js"></script>
<script>Holdy.init({ apiKey: 'hol_live_...' })</script>

Ou como pacote no seu build:

npm install @holdyapp/sdk

import { initHoldy } from '@holdyapp/sdk/web'

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

Opções do initHoldy: autoCapture (pageview a cada rota, padrão ligado), friction (cliques sem efeito, cliques de raiva, erros de JS, requisições lentas e formulários abandonados, padrão ligado; aceita um objeto pra ajustar limiares), release (a versão do produto no ar, como o sha do commit ou o número do build; com ela a Holdy diz em que versão um erro apareceu), flushAt, flushIntervalMs e debug.

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. Quando a página é escondida ou fechada, o que restar na fila é enviado com fetch em modo keepalive.
Retry seguro — cada evento sai com um id próprio, então reenviar um lote nunca duplica. Erro de rede e 5xx esperam com backoff exponencial; 429 respeita o Retry-After. Chave inválida ou origem não permitida descartam o lote e avisam uma vez no console.