Novo por aqui? Comece pelo Getting Started antes de seguir esta página.

Paywalls

Crie e exiba paywalls visuais no seu app sem precisar publicar nova versão

TL;DR: Paywalls são telas de oferta criadas no dashboard e exibidas no app com uma linha de código. Esta página cobre como criar no dashboard, a API do SDK, pré-carregamento e integração com feature flags.

O que são Paywalls?

Paywalls são telas visuais que apresentam seus produtos e planos de assinatura para os usuários. Com o Paywallo, você cria paywalls no editor visual do dashboard e pode exibi-los no app chamando uma única linha de código.

A grande vantagem é que você pode atualizar design, textos, produtos e preços remotamente, sem precisar enviar uma nova versão para as lojas.

Exemplo Rápido

Exibindo um paywall

import { Paywallo } from '@virex-tech/paywallo-sdk'; // Exibir paywall por placement const result = await Paywallo.presentPaywall('onboarding'); // Verificar resultado if (result.purchased) { console.log('Compra realizada!', result.productId); // Liberar acesso premium } else if (result.cancelled) { console.log('Usuário fechou o paywall'); // Continuar com versão gratuita } else if (result.restored) { console.log('Compras restauradas'); }

Criando Paywalls no Dashboard

Passos para criar um paywall

Acesse Paywalls no menu lateral
Clique em Novo Paywall
Escolha um template ou comece do zero
Use o editor visual para adicionar blocos (texto, imagem, botão de compra, etc)
Configure os produtos que serão exibidos
Teste a visualização em diferentes dispositivos (iOS/Android, light/dark mode)
Salve e publique o paywall
Crie uma campanha em Campanhas para associar o paywall a um placement

Dicas de Boas Práticas

•Sempre teste o paywall em dispositivos reais antes de publicar para produção
•Use placements descritivos que indiquem claramente onde o paywall será exibido
•Não exiba paywalls demais - isso pode irritar os usuários. Seja estratégico sobre quando e onde mostrar
•Use o sistema de campanhas para fazer testes A/B e encontrar o paywall mais eficiente

Referência da API

O que é um Placement?

Um placement é um identificador que conecta seu código a uma campanha no dashboard (ex: 'premium_upsell', 'onboarding_offer'). Você define o nome no código e depois cria uma campanha no dashboard associada a esse mesmo nome — o SDK resolve qual paywall exibir automaticamente.

Parâmetros

`Paywallo.presentPaywall()`

Parâmetro	Tipo	Obrigatório	Descrição
`placement`	string	Sim	Identificador do placement (ex: "onboarding", "settings")
`fallback`	string	Não	ID do paywall fallback caso não haja campanha ativa

Objeto de Retorno

PaywallResult

O método presentPaywall() retorna uma Promise com este objeto:

Propriedade	Tipo	Descrição
`presented`	boolean	true se o paywall foi exibido
`purchased`	boolean	true se o usuário completou uma compra
`cancelled`	boolean	true se o usuário fechou sem comprar
`restored`	boolean	true se o usuário restaurou compras anteriores
`productId`	string?	ID do produto comprado (se purchased = true)
`error`	Error?	Erro (se houver falha)

Exemplo completo de tratamento

async function showPremiumPaywall() { try { const result = await Paywallo.presentPaywall('upgrade_cta'); if (result.purchased) { // Usuário comprou Alert.alert('Sucesso!', 'Bem-vindo ao Premium'); navigation.navigate('PremiumFeatures'); } else if (result.cancelled) { // Usuário fechou console.log('Paywall cancelled by user'); } else if (result.restored) { // Usuário restaurou compras console.log('Purchases restored'); } else if (result.error) { // Erro ao exibir paywall Alert.alert('Erro', result.error.message); } } catch (error) { console.error('Failed to present paywall:', error); } }

Como Funcionam os Placements

Placements são "slots" onde você pode exibir paywalls. Cada placement pode ter uma ou mais campanhas ativas, e o Paywallo decide qual paywall mostrar baseado nas regras de segmentação.

Exemplos de Placements:

onboarding — Mostrado após o tutorial
settings — Botão na tela de configurações
feature_locked — Quando o usuário tenta acessar uma feature premium
app_launch — Ao abrir o app (use com cuidado!)

Configure placements e campanhas no dashboard em Campanhas. Você pode criar múltiplas campanhas para o mesmo placement e fazer testes A/B.

Pronto para configurar campanhas? Veja a documentação de Campanhas →

Pré-carregamento para Exibição Instantânea

Por que pré-carregar?

Quando você chama presentPaywall() ou presentCampaign(), o SDK precisa:

Buscar dados do paywall na API
Carregar informações dos produtos (preços) das lojas (Apple/Google)
Baixar as imagens do paywall

Isso pode causar um delay de 1-3 segundos até o paywall aparecer. Com preloadCampaign(), você faz tudo isso antecipadamente, e quando o usuário precisar ver o paywall, ele aparece instantaneamente.

Exemplo: Pré-carregamento após inicialização

import { Paywallo } from '@virex-tech/paywallo-sdk'; import { useEffect } from 'react'; function App() { useEffect(() => { // Inicializa o SDK Paywallo.init({ appKey: 'sua_app_key', }); // Pré-carrega o paywall de onboarding em background Paywallo.preloadCampaign('onboarding'); }, []); return <MainNavigator />; }

Exemplo: Exibição instantânea

// Em qualquer tela do app, o paywall aparece instantaneamente // porque já foi pré-carregado async function showPaywall() { const result = await Paywallo.presentCampaign('onboarding'); if (result.purchased) { // Usuário comprou! } }

O cache do preload dura 5 minutos. Após esse tempo, o SDK buscará os dados novamente na próxima chamada.

Boas Práticas de Pré-carregamento

• Pré-carregue logo após Paywallo.init() para máximo tempo de cache
• Use em paywalls que serão exibidos frequentemente (onboarding, upgrade CTAs)
• O preload funciona em background e não bloqueia a UI do app
• Se o preload falhar, o paywall ainda funciona (carrega on-demand)

Integração com Feature Flags

Use feature flags para controlar qual paywall exibir aos usuários, permitindo testes A/B e rollouts graduais.

Exemplo: Paywall Condicional

Verifique uma feature flag antes de decidir qual paywall exibir

TypeScript

import { Paywallo } from "@virex-tech/paywallo-sdk"; // Verifica flag antes de apresentar paywall const useCustomPaywall = await Paywallo.getConditionalFlag("test_paywall"); if (useCustomPaywall) { // Apresenta paywall customizada do Paywallo const result = await Paywallo.presentPaywall("premium_offer"); if (result.purchased) { // Usuário comprou } } else { // Apresenta paywall nativa do app showNativePaywall(); }

Usando getVariant para testes A/B

import { Paywallo } from "@virex-tech/paywallo-sdk"; // Obtém a variante do usuário para o teste const variant = await Paywallo.getVariant("paywall_ab_test"); if (variant.key === "variant_b") { // Exibe paywall da variante B await Paywallo.presentPaywall("premium_offer_b"); } else { // Exibe paywall padrão (controle) await Paywallo.presentPaywall("premium_offer"); }

Eventos de Paywall

Eventos são rastreados automaticamente quando o usuário interage com a paywall

Evento	Descrição	Propriedades
$paywall_viewed	Paywall foi exibida	placement, paywallId
$paywall_dismissed	Usuário fechou sem comprar	placement, paywallId
$paywall_purchased	Compra realizada	placement, paywallId, productId

Boas Práticas

• Use feature flags para testes A/B entre paywalls
• Sempre tenha um fallback caso a flag não carregue
• Monitore métricas de conversão por variante
• Teste em sandbox antes de ativar em produção