Referência do SDK

Todos os métodos, hooks e tipos do SDK com exemplos de uso

Pacote: @virex-tech/paywallo-sdk

TL;DR

Envolva seu app com <PaywalloProvider>, chame Paywallo.identify() após o login e use Paywallo.track() para registrar eventos. Todos os métodos assíncronos retornam Promises — use await.

Todos os métodos assíncronos retornam Promises. Use await ou .then() para tratar os resultados.

Nesta página

Provider & Setup

<PaywalloProvider>

Descrição: Componente wrapper obrigatório que inicializa o SDK e fornece contexto para todos os hooks. Deve envolver seu app no nível raiz.

import { PaywalloProvider } from '@virex-tech/paywallo-sdk'; function App() { return ( <PaywalloProvider config={{ appKey: 'your_app_key', // baseUrl: 'https://sua-api.com', // opcional debug: __DEV__, environment: 'Production', }} > <YourApp /> </PaywalloProvider> ); }
PropTipoObrigatórioDescrição
config.appKeystringSimSua App Key do dashboard
config.baseUrlstringNãoURL da API (opcional, já configurado por padrão)
config.debugbooleanNãoAtiva logs de debug (padrão: false)
config.environment'Production' | 'Sandbox'NãoModo do ambiente (padrão: Production)

Inicialização

Paywallo.init()

Este método é chamado automaticamente pelo <PaywalloProvider>. Use diretamente apenas se precisar de inicialização manual fora do React.

Descrição: Inicializa o SDK com sua configuração. Obrigatório antes de usar qualquer outro método.

import { Paywallo } from '@virex-tech/paywallo-sdk'; // Inicialização manual (não recomendado para apps React) await Paywallo.init({ appKey: 'your_app_key', debug: false, environment: 'Production', });
ParâmetroTipoObrigatórioDescrição
config.appKeystringSimApp Key do dashboard
config.baseUrlstringNãoURL base da API (obrigatório em produção)
config.debugbooleanNãoAtiva logs de debug (padrão: false)
config.environment'Production' | 'Sandbox'NãoAmbiente de execução (padrão: Production)
config.sessionConfig{ sessionTimeoutMs?: number; trackAppState?: boolean }NãoConfigurações de sessão: timeout em ms e monitoramento de estado do app
config.autoStartSessionbooleanNãoInicia sessão automaticamente ao inicializar (padrão: true)
config.offlineQueueEnabledbooleanNãoAtiva fila offline de eventos (padrão: true)
config.timeoutnumberNãoTimeout das requisições HTTP em milissegundos

Identidade do Usuário

Paywallo.identify()

Descrição: Identifica o usuário atual com email e propriedades customizadas. Associa todos os eventos futuros a este usuário.

Este método NÃO aceita um parâmetro userId. A identificação do usuário é baseada no distinctId gerado pelo SDK combinado com o email.

import { Paywallo } from '@virex-tech/paywallo-sdk'; // Identify user after login Paywallo.identify({ email: 'user@example.com', properties: { name: 'John Doe', plan: 'premium', signupDate: '2024-01-15', }, });
ParâmetroTipoObrigatórioDescrição
options.emailstringNãoE-mail do usuário
options.propertiesobjectNãoPropriedades customizadas (name, plan, etc)

Paywallo.getDistinctId()

Descrição: Retorna o ID único do usuário gerado pelo SDK. Este ID persiste entre as sessões do app.

const distinctId = Paywallo.getDistinctId(); console.log('User ID:', distinctId); // Output: "usr_abc123def456"

Retorna:

string

Paywallo.getDeviceId()

Descrição: Retorna o ID do dispositivo usado para rastreamento em nível de dispositivo. Pode retornar null se o ID ainda não estiver disponível.

const deviceId = Paywallo.getDeviceId(); if (deviceId) { // usar deviceId }

Retorna:

string | null

Paywallo.getEmail()

Descrição: Retorna o endereço de e-mail associado ao usuário atual, se houver.

const email = Paywallo.getEmail(); if (email) { console.log('User email:', email); }

Retorna:

string | null

Paywallo.reset()

Descrição: Limpa a identidade do usuário atual. Use ao fazer logout. O distinctId será regenerado na próxima sessão.

// On user logout async function handleLogout() { await signOut(); Paywallo.reset(); }

Paywallo.fullReset()

Descrição: Realiza um reset completo do SDK, limpando todos os dados em cache. Requer re-inicialização após a chamada.

Operação destrutiva. Use apenas quando precisar resetar completamente o estado do SDK, como durante desenvolvimento ou ao trocar de conta.

// Reset completo - requer re-inicialização Paywallo.fullReset(); // Re-inicializar após full reset await Paywallo.init({ appKey: 'your_app_key', });

Analytics & Eventos

Paywallo.track()

Descrição: Registra um evento customizado com propriedades opcionais.

Nomes de eventos devem usar o formato snake_case (ex: button_clicked, não buttonClicked).

import { Paywallo } from '@virex-tech/paywallo-sdk'; // Track a simple event Paywallo.track('feature_used'); // Track with properties Paywallo.track('button_clicked', { properties: { button_id: 'cta_premium', screen: 'home', variant: 'blue', }, }); // Track purchase event Paywallo.track('purchase_completed', { properties: { product_id: 'monthly_premium', price: 9.99, currency: 'USD', }, });
ParâmetroTipoObrigatórioDescrição
eventNamestringSimNome do evento (snake_case)
options.propertiesobjectNãoDados adicionais do evento

Feature Flags

Paywallo.getVariant()

Descrição: Retorna a variante atribuída para um teste A/B ou feature flag, incluindo a chave da variante e payload opcional.

import { Paywallo } from '@virex-tech/paywallo-sdk'; const { variant, payload } = await Paywallo.getVariant('homepage_layout'); if (variant === 'new_design') { // Show new design const buttonColor = payload?.buttonColor || 'blue'; } else { // Show control (original design) }
ParâmetroTipoObrigatórioDescrição
flagKeystringSimIdentificador do feature flag

Retorna:

{
  variant: string | null,  // null se o flag não for encontrado
  payload?: object,        // Payload JSON opcional
}

Paywallo.getConditionalFlag()

Descrição: Avalia um feature flag condicional com base no contexto. Retorna um booleano indicando se o flag está ativo para o contexto fornecido.

import { Paywallo } from '@virex-tech/paywallo-sdk'; // Simple check const isEnabled = await Paywallo.getConditionalFlag('dark_mode'); // With context for conditional evaluation const showBetaFeature = await Paywallo.getConditionalFlag('beta_feature', { platform: 'ios', appVersion: '2.1.0', country: 'US', }); if (showBetaFeature) { // Show beta feature }
ParâmetroTipoObrigatórioDescrição
flagKeystringSimIdentificador do feature flag
context.platformstringNãoPlataforma (ios, android)
context.appVersionstringNãoVersão do app
context.countrystringNãoCódigo do país
context.distinctIdstringNãoOverride do ID do usuário

Retorna:

Promise<boolean>

Paywalls & Campanhas

Paywallo.getPaywall()

Descrição: Busca a configuração do paywall para um placement. Use para construir UIs de paywall customizadas.

const paywall = await Paywallo.getPaywall('premium_feature'); console.log(paywall.title); console.log(paywall.products);
ParâmetroTipoObrigatórioDescrição
placementstringSimIdentificador do placement

Paywallo.presentPaywall()

Descrição: Exibe um modal de paywall. Requer que o app esteja envolto pelo <PaywalloProvider>.

const result = await Paywallo.presentPaywall('onboarding'); if (result.purchased) { console.log('Purchased:', result.productId); } else if (result.cancelled) { console.log('User dismissed paywall'); } else if (result.restored) { console.log('Purchases restored'); } else if (result.error) { console.error('Error:', result.error); }
ParâmetroTipoObrigatórioDescrição
placementstringSimIdentificador do placement

Retorna:

{
  presented: boolean,
  purchased: boolean,
  cancelled: boolean,
  restored: boolean,
  productId?: string,
  transactionId?: string,
  error?: Error,
}

Paywallo.getCampaign()

Descrição: Busca dados de campanha para um placement com contexto opcional para segmentação.

const campaign = await Paywallo.getCampaign('onboarding', { platform: 'ios', country: 'US', }); console.log(campaign.variantKey); console.log(campaign.paywall);
ParâmetroTipoObrigatórioDescrição
placementstringSimIdentificador do placement
contextobjectNãoContexto de segmentação

Paywallo.presentCampaign()

Descrição: Exibe um modal de paywall de campanha com atribuição de variante A/B.

const result = await Paywallo.presentCampaign('onboarding', { platform: 'ios', }); if (result.purchased) { console.log('Campaign ID:', result.campaignId); console.log('Variant:', result.variantKey); console.log('Product:', result.productId); }

Retorna:

{
  presented: boolean,
  purchased: boolean,
  cancelled: boolean,
  restored: boolean,
  productId?: string,
  campaignId?: string,
  variantKey?: string,
  error?: string,
}

Paywallo.preloadCampaign() Performance

Descrição: Pré-carrega uma campanha (dados do paywall, produtos IAP, imagens) para exibição instantânea. Chame cedo (ex: no launch do app) para placements que você espera exibir em breve.

// Preload on app launch useEffect(() => { Paywallo.preloadCampaign('onboarding'); Paywallo.preloadCampaign('premium_feature'); }, []); // Later, display instantly (no loading delay) const result = await Paywallo.presentCampaign('onboarding');
ParâmetroTipoObrigatórioDescrição
placementstringSimIdentificador do placement
contextobjectNãoContexto de segmentação

Paywallo.getPreloadedCampaign()

Descrição: Retorna uma campanha pré-carregada do cache. Retorna null se não foi pré-carregada.

const cached = Paywallo.getPreloadedCampaign('onboarding'); if (cached) { // Campaign is ready, present immediately await Paywallo.presentCampaign('onboarding'); } else { // Not preloaded, show loading state setLoading(true); await Paywallo.presentCampaign('onboarding'); setLoading(false); }

Assinaturas

Paywallo.hasActiveSubscription()

Descrição: Verifica se o usuário atual possui uma assinatura ativa.

const hasSubscription = await Paywallo.hasActiveSubscription(); if (!hasSubscription) { // Show paywall await Paywallo.presentPaywall('premium_gate'); }

Retorna:

Promise<boolean>

Paywallo.getSubscription()

Descrição: Retorna os detalhes completos da assinatura do usuário atual.

const subscription = await Paywallo.getSubscription(); if (subscription) { console.log('Product:', subscription.productId); console.log('Status:', subscription.status); console.log('Expires:', subscription.expiresAt); console.log('Auto-renew:', subscription.autoRenewEnabled); }

Retorna:

{
  productId: string,
  status: 'active' | 'expired' | 'cancelled' | 'grace_period',
  expiresAt: string,          // ISO date string
  platform: 'ios' | 'android',
  autoRenewEnabled: boolean,
} | null

Paywallo.restorePurchases()

Descrição: Restaura compras anteriores da loja. Obrigatório para conformidade com a App Store.

async function handleRestore() { try { const result = await Paywallo.restorePurchases(); if (result.restored) { Alert.alert('Success', 'Your purchases have been restored!'); } else { Alert.alert('No Purchases', 'No previous purchases found.'); } } catch (error) { Alert.alert('Error', 'Could not restore purchases.'); } }

Paywallo.requireSubscription()

Descrição: Garante que o usuário possui assinatura ativa. Se não, exibe automaticamente um paywall. Retorna true se o usuário tem ou acabou de adquirir uma assinatura.

async function acessarConteudoPremium() { const temAcesso = await Paywallo.requireSubscription('premium_content'); if (temAcesso) { // Usuário tem assinatura ou acabou de comprar exibirConteudoPremium(); } else { // Usuário fechou o paywall sem comprar exibirPromocaoDeUpgrade(); } }
ParâmetroTipoObrigatórioDescrição
placementstringNãoPlacement do paywall a exibir (padrão: default)

Retorna:

Promise<boolean>

Paywallo.gateContent()

Descrição: Protege conteúdo premium com verificação de assinatura. Executa a função fornecida somente se o usuário tiver assinatura ativa, caso contrário exibe o paywall.

// Proteção de ação premium const resultado = await Paywallo.gateContent( async () => { // Executa somente se o usuário tiver assinatura return await baixarConteudoPremium(); }, 'download_gate' ); if (resultado) { // conteúdo baixado com sucesso }
ParâmetroTipoObrigatórioDescrição
fn() => Promise<T>SimFunção a executar se assinado
placementstringNãoPlacement do paywall

Retorna:

Promise<T | null>

Paywallo.requireSubscriptionWithCampaign()

Descrição: Funciona igual ao requireSubscription, mas usa o sistema de campanhas para exibir a paywall. Permite A/B testing automático via campanhas configuradas no dashboard.

const temAcesso = await Paywallo.requireSubscriptionWithCampaign( 'premium_onboarding', { source: 'quiz_end' } ); if (temAcesso) { navegarParaConteudoPremium(); }
ParâmetroTipoObrigatórioDescrição
placementstringSimIdentificador do placement da campanha
contextRecord<string, unknown>NãoContexto adicional repassado à campanha para segmentação

Retorna:

Promise<boolean>

Paywallo.gateContentWithCampaign()

Descrição: Funciona igual ao gateContent, mas usa o sistema de campanhas para exibir a paywall, habilitando A/B testing automático.

const resultado = await Paywallo.gateContentWithCampaign( async () => { return await baixarConteudoPremium(); }, 'download_gate', { plan: 'trial' } ); if (resultado) { exibirConteudo(resultado); }
ParâmetroTipoObrigatórioDescrição
fn() => Promise<T>SimFunção executada somente se o usuário tiver assinatura ativa
placementstringSimIdentificador do placement da campanha
contextRecord<string, unknown>NãoContexto adicional repassado à campanha para segmentação

Retorna:

Promise<T | null>

React Hooks

Estes hooks fornecem acesso reativo ao estado do SDK e devem ser usados dentro de um <PaywalloProvider>.

usePaywallo()

Descrição: Hook principal para acessar o estado do SDK e métodos comuns.

import { usePaywallo } from '@virex-tech/paywallo-sdk'; function MyComponent() { const { isInitialized, distinctId, presentPaywall, presentCampaign, preloadCampaign, hasActiveSubscription, } = usePaywallo(); const handlePremiumFeature = async () => { const hasSubscription = await hasActiveSubscription(); if (!hasSubscription) { await presentPaywall('premium_feature'); } }; return ( <Button onPress={handlePremiumFeature}> Unlock Premium </Button> ); }

Retorna:

{
  config: PaywalloConfig | null,
  isInitialized: boolean,
  distinctId: string | null,
  subscription: Subscription | null,
  products: Map<string, Product>,
  isLoadingProducts: boolean,
  presentPaywall: (placement: string) => Promise<PaywallResult>,
  presentCampaign: (placement: string, context?) => Promise<CampaignResult>,
  preloadCampaign: (placement: string, context?) => Promise<PreloadResult>,
  hasActiveSubscription: () => Promise<boolean>,
  getSubscription: () => Promise<Subscription | null>,
  restorePurchases: () => Promise<{ success: boolean; error?: Error }>,
  getPaywallConfig: (placement: string) => Promise<PaywallConfig | null>,
  refreshProducts: (productIds: string[]) => Promise<void>,
}

useSubscription()

Descrição: Hook para estado reativo de assinatura e gerenciamento.

import { useSubscription } from '@virex-tech/paywallo-sdk'; function SubscriptionStatus() { const { subscription, isActive, isLoading, error, entitlements, refresh, restore, } = useSubscription(); if (isLoading) return <Loading />; return ( <View> <Text>Status: {isActive ? 'Active' : 'Inactive'}</Text> {subscription && ( <Text>Expires: {subscription.expiresAt}</Text> )} <Button onPress={restore}>Restore Purchases</Button> </View> ); }

Retorna:

{
  subscription: Subscription | null,
  isActive: boolean,
  isLoading: boolean,
  error: Error | null,
  entitlements: string[],
  refresh: () => Promise<void>,
  restore: () => Promise<void>,
}

usePurchase()

Descrição: Hook para gerenciar compras in-app com estados de carregamento.

import { usePurchase } from '@virex-tech/paywallo-sdk'; function PurchaseButton({ productId }) { const { state, purchase, restore, error, isLoading, isPurchasing, isRestoring, } = usePurchase(); const handlePurchase = async () => { try { const result = await purchase(productId); // result é IAPPurchase: { productId, transactionId, transactionDate, ... } void result; } catch (err) { // compra falhou ou foi cancelada void err; } }; return ( <Button onPress={handlePurchase} disabled={isPurchasing} > {isPurchasing ? 'Processing...' : 'Buy Now'} </Button> ); }

Retorna:

{
  state: 'idle' | 'loading' | 'purchasing' | 'restoring' | 'error',
  purchase: (productId: string) => Promise<IAPPurchase>,
  restore: () => Promise<IAPPurchase[]>,
  error: PurchaseError | null,
  isLoading: boolean,
  isPurchasing: boolean,
  isRestoring: boolean,
}

useProducts()

Descrição: Hook para carregar e acessar informações de produtos das lojas. Aceita um parâmetro opcional initialProductIds para carregar produtos automaticamente na montagem.

import { useProducts } from '@virex-tech/paywallo-sdk'; function ProductList() { // Opção 1: passar IDs na inicialização (carrega automaticamente) const { products, formattedProducts, isLoading, error, loadProducts, getProduct, } = useProducts(['monthly_premium', 'yearly_premium']); // Opção 2: carregar manualmente depois // const { loadProducts } = useProducts(); // useEffect(() => { loadProducts(['monthly_premium']); }, []); return ( <View> {formattedProducts.map(product => ( <ProductCard key={product.id} title={product.title} price={product.localizedPrice} /> ))} </View> ); }

Retorna:

{
  products: IAPProduct[],
  formattedProducts: FormattedProduct[],
  isLoading: boolean,
  error: Error | null,
  loadProducts: (productIds: string[]) => Promise<void>,
  getProduct: (productId: string) => IAPProduct | undefined,
  getFormattedProduct: (productId: string) => FormattedProduct | undefined,
  getPriceInfo: (productId: string) => ProductPriceInfo | undefined,
}

Gerenciamento de Sessão

Paywallo.startSession()

Descrição: Inicia uma nova sessão de analytics. Normalmente chamado automaticamente quando o app vai para foreground.

// Manual session start (usually not needed) Paywallo.startSession();

Paywallo.endSession()

Descrição: Encerra a sessão atual. Normalmente chamado automaticamente quando o app vai para background.

// Manual session end (usually not needed) Paywallo.endSession();

Paywallo.getSessionId()

Descrição: Retorna o ID da sessão atual.

const sessionId = Paywallo.getSessionId(); console.log('Session:', sessionId);

Retorna:

string | null

Ambiente

Paywallo.getEnvironment()

Descrição: Retorna o ambiente atual (Production ou Sandbox).

const env = Paywallo.getEnvironment(); console.log('Environment:', env); // 'Production' or 'Sandbox'

Retorna:

'Production' | 'Sandbox'

Paywallo.setEnvironment()

Descrição: Alterna entre os ambientes Production e Sandbox. Útil para testes.

// Switch to sandbox for testing if (__DEV__) { Paywallo.setEnvironment('Sandbox'); }
ParâmetroTipoObrigatórioDescrição
environment'Production' | 'Sandbox'SimAmbiente alvo

Rede & Offline

Paywallo.isOnline()

Descrição: Verifica se o dispositivo possui conectividade de rede.

const online = Paywallo.isOnline(); if (!online) { mostrarMensagemOffline(); }

Retorna:

boolean

Paywallo.getOfflineQueueSize()

Descrição: Retorna o número de eventos enfileirados enquanto offline.

const tamanhoFila = Paywallo.getOfflineQueueSize(); // ex: 42 eventos pendentes

Retorna:

number

Paywallo.processOfflineQueue()

Descrição: Processa manualmente a fila offline de eventos. Normalmente é disparado de forma automática ao restaurar a conectividade.

// Forçar processamento da fila offline const { processed, failed } = await Paywallo.processOfflineQueue();

Retorna:

Promise<{ processed: number; failed: number }>

Paywallo.clearOfflineQueue()

Descrição: Descarta todos os eventos atualmente enfileirados na fila offline. Útil para limpar dados obsoletos ou em situações de reset da sessão do usuário.

// Limpar fila offline (ex: após logout) await Paywallo.clearOfflineQueue();

Retorna:

Promise<void>

Tipos TypeScript

Definições de Tipos

O SDK é escrito em TypeScript e exporta todos os tipos necessários para segurança de tipos completa.

import type { PaywalloConfig, PaywallResult, CampaignResult, Subscription, FlagVariant, Product, UserProperties, EventProperties, } from '@virex-tech/paywallo-sdk';

PaywalloConfig

interface PaywalloConfig {
  appKey: string;
  baseUrl?: string;
  debug?: boolean;
  environment?: 'Production' | 'Sandbox';
}

PaywallResult

interface PaywallResult {
  presented: boolean;
  purchased: boolean;
  cancelled: boolean;
  restored: boolean;
  productId?: string;
  transactionId?: string;
  error?: Error;
}

CampaignResult

interface CampaignResult extends PaywallResult {
  campaignId?: string;
  variantKey?: string;
}

Subscription

interface Subscription {
  productId: string;
  status: 'active' | 'expired' | 'cancelled' | 'in_billing_retry' | 'in_grace_period' | 'revoked';
  expiresAt: Date | null;
  platform: 'ios' | 'android';
  autoRenewEnabled: boolean;
  inGracePeriod: boolean;
}

FlagVariant

interface FlagVariant {
  variant: string | null;
  payload?: Record<string, unknown>;
}
Paywallo | Analytics, Gestão de Paywalls e Feature Flags