@groundbrick/h2b2-sveltekit

H2B2 analytics para apps SvelteKit, imune a ad blockers:

• Server-side: cada page load vira um server_pageview (rota, usuário, device, duração) capturado no backend — funciona mesmo com JS bloqueado.
• Relay first-party: o SDK roda no browser mas envia tudo para um endpoint do próprio domínio do app (/collect), que repassa server-to-server ao H2B2. Nenhuma request para domínio de terceiro; a API key nunca chega ao browser.
• Proxy de widgets: os módulos de questions/tours do H2B2 também ficam first-party — o script legado é servido em /collect/sdk.js e as chamadas de widget passam por /collect/api/*, tudo same-origin.

Instalação

pnpm add @groundbrick/h2b2-sveltekit

1. Hook do servidor (src/hooks.server.ts)

import { sequence } from '@sveltejs/kit/hooks';
import { createH2B2Handle } from '@groundbrick/h2b2-sveltekit';
import { env } from '$env/dynamic/private';

const h2b2 = createH2B2Handle({
  h2b2Url: env.H2B2_URL,        // ex.: https://h2b2.example.com
  apiKey: env.H2B2_API_KEY,     // API key da campanha (dashboard do H2B2)
  getUser: (event) => event.locals.user
    ? { id: event.locals.user.id, email: event.locals.user.email, name: event.locals.user.name }
    : null
});

// Depois do handle de auth, para getUser enxergar event.locals
export const handle = sequence(authHandle, h2b2);

2. SDK no browser (src/routes/+layout.svelte)

<script>
  import { onMount } from 'svelte';
  import { initH2B2 } from '@groundbrick/h2b2-sveltekit/client';

  onMount(() => initH2B2());
</script>

3. Uso

<!-- clique rastreado automaticamente -->
<button data-h2b2-track="checkout-confirmar">Confirmar</button>

// evento custom
import { track } from '@groundbrick/h2b2-sveltekit/client';
track('plano_assinado', { plano: 'pro' });

Capturado automaticamente: pageviews (server + SPA), cliques [data-h2b2-track], submits de formulário (metadados, nunca valores), scroll depth, Web Vitals (LCP/FCP/TTFB/CLS).

4. Widgets de feedback e tours (opcional)

Para usar os widgets de questions/tours do H2B2 no app alvo, carregue o SDK pelo proxy same-origin — nada toca o domínio do H2B2 no browser.

O proxy é obrigatório, não uma optimização: os endpoints de widget do H2B2 exigem a apiKey da campanha e não servem CORS. O proxy anexa a key server-side, pelo que ela nunca chega ao browser; carregar o SDK directamente do domínio do H2B2 devolve 401.

<svelte:head>
  <script src="/collect/sdk.js"></script>
</svelte:head>
<script>
  import { onMount } from 'svelte';
  onMount(() => window.H2B2?.init());
  // Sem campaignId: a campanha vem sempre da apiKey que o proxy anexa.
  // apiUrl default = /collect/api (proxy); session e user são injetados pelo servidor
</script>

Opções (createH2B2Handle)

| Opção | Default | Descrição | |---|---|---| | h2b2Url | — | URL base do H2B2 (obrigatório) | | apiKey | — | API key da campanha (obrigatório, só no servidor) | | collectPath | /collect | Path same-origin do relay | | getUser | — | (event) => { id, email?, name? } do usuário logado | | exclude | [] | Prefixos/regex de paths a não rastrear | | flushIntervalMs | 5000 | Intervalo de flush do batch | | maxBatchSize | 20 | Tamanho do batch | | debug | false | Loga falhas de tracking no console |