# Eventos e analytics

Registre ações do usuário com track() e rastreie telas automaticamente com o hook de navegação.

## Enviar eventos customizados

Chame `track(eventName, properties)` para registrar qualquer ação relevante. O campo `properties` aceita `string | number | boolean | null`.

```typescript
import Paywallo from "@virex-tech/paywallo-sdk";

// Exemplo: usuário completou um quiz
await Paywallo.track("quiz_completed", {
  properties: {
    quiz_id: "weight_loss_v2",
    answers_count: 12,
    skipped: false,
    score: null,
  },
});
```

`string` Texto (ex: feature, plan_id, country)

`number` Número inteiro ou decimal (ex: amount, step_index)

`boolean` Verdadeiro/falso (ex: skipped, is_trial)

`null` Ausência de valor: omite o campo na análise

## Prioridade crítica

Por padrão o SDK acumula os eventos e envia em lote: o que vier primeiro entre 25 eventos ou 10 segundos. Para um evento seu que não pode ser perdido, como escolha de plano ou aceite de termos, passe `priority: "critical"`. O evento sai na hora, num lote de 1, e é reenviado se a rede falhar. O lote normal, no mesmo cenário, é descartado. Não use a prioridade crítica nos eventos automáticos da lista abaixo: o SDK já os envia com a prioridade certa.

```typescript
// priority: "critical" envia o evento imediatamente (batch-of-1),
// sem aguardar a janela de 25 eventos / 10 segundos.
//
// Use so em evento SEU que nao pode ser perdido. Nao reemita os automaticos
// (lista abaixo) — o SDK ja os envia, e chamar na mao conta duas vezes.
await Paywallo.track("plano_escolhido", {
  properties: {
    plan_id: planId,
    origem: "tela_de_precos",
  },
  priority: "critical",
});
```

## Eventos automáticos

Não chame `track()` para os eventos abaixo: o SDK já os dispara, e chamar de novo conta o evento duas vezes. A exceção é o screen_view, que só sai automático com o hook de navegação do React Native. Nas demais plataformas, dispare você mesmo: com um observer de navegação (Kotlin e Flutter) ou chamando track() diretamente em cada tela (Swift).

-   `$app_installed` Primeira abertura do app com dados de atribuição de anúncio. Gerenciado pelo InstallTracker.
-   `lifecycle` Ciclo de vida do app, com o tipo no payload: {type: "install" | "cold_start" | "session_start" | "foreground" | "background" | "session_end"}. Alimenta DAU/MAU no dashboard.
-   `transaction` Compra confirmada, emitida pelo IAPTransactionEmitter e pela ponte do Superwall.
-   `checkout_started` Início de compra, emitido quando o usuário toca em comprar, antes de a loja abrir. Conta mesmo quando ele cancela a tela de pagamento.
-   `screen_view` Navegação de tela. A forma de disparo, automática ou manual, depende da integração de navegação disponível na plataforma. Veja a seção de rastreamento de telas para os detalhes.
-   `notification` Entrega, clique e descarte de push, emitido pelo NotificationEventTracker.

Compras e onboarding têm APIs próprias no SDK: `onboardingStep()` para cada etapa do onboarding. A assinatura muda conforme a linguagem, mas o papel do método é o mesmo.

## Rastreamento de telas

Se a navegação da plataforma tiver um hook ou listener de troca de rota, registre-o uma vez no ponto raiz da navegação do app. A partir daí o SDK emite `screen_view` a cada troca de tela, sem precisar chamar track() manualmente em cada uma.

Sem um hook de navegação disponível, ou quando preferir não usá-lo, dispare track() manualmente no callback de exibição de cada tela. É o único caminho no Swift nativo, que não tem hook equivalente. Nas demais plataformas é a alternativa para quando o app não usa o framework de navegação padrão, por exemplo React Native sem React Navigation.

```typescript
import { usePaywalloScreenTracking } from "@virex-tech/paywallo-sdk";
import { NavigationContainer } from "@react-navigation/native";

export function App() {
  const onStateChange = usePaywalloScreenTracking();

  return (
    <NavigationContainer onStateChange={onStateChange}>
      {/* suas rotas */}
    </NavigationContainer>
  );
}
```

```typescript
// Sem React Navigation: envie screen_view manualmente
await Paywallo.track("screen_view", {
  properties: { screen_name: "OnboardingStep3" },
});
```

## Ver no dashboard

Eventos customizados enviados via `track()` aparecem em **Métricas Customizadas** no dashboard, com o volume das últimas 24h e dos últimos 30 dias por nome de evento. Clique num evento pra ver o histórico e a tendência.