Eventos e analytics

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

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,
  },
});

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.

// 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",
});

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_installedPrimeira abertura do app com dados de atribuição de anúncio. Gerenciado pelo InstallTracker.
• lifecycleCiclo de vida do app, com o tipo no payload: {type: "install" | "cold_start" | "session_start" | "foreground" | "background" | "session_end"}. Alimenta DAU/MAU no dashboard.
• transactionCompra confirmada, emitida pelo IAPTransactionEmitter e pela ponte do Superwall.
• checkout_startedIní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_viewNavegaçã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.
• notificationEntrega, 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.

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.

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>
  );
}

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

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.