RevenueCat (mobile)

O RevenueCat gerencia assinaturas e compras no app para iOS e Android. Conecta a App Store e a Play Store ao seu backend, sincroniza o status premium e dispara webhooks quando uma compra acontece.

ImplementaçãoCopiar link da âncora

Fase 1: Test Store (sem conta Apple ou Google)Copiar link da âncora

O RevenueCat tem um ambiente chamado Test Store que simula compras sem precisar de conta na Apple ou Google. Ideal para validar o fluxo completo antes de configurar as lojas reais.

1. Criar conta e projeto no RevenueCatCopiar link da âncora

Acesse app.revenuecat.com → crie uma conta gratuita → crie um projeto.

2. Pegar a chave do Test StoreCopiar link da âncora

Todo projeto RevenueCat já nasce com um app Test Store pronto, você não precisa criar nada. A chave fica em API keys → SDK API keys → Test Store.

Copie a chave test_xxx exibida.

3. Criar Produtos, Entitlements e OfferingsCopiar link da âncora

Pelo painel RC (ou via MCP do RevenueCat):

• Products → + New → crie os planos (ex: premium_monthly, premium_annual)
• Entitlements → + New → crie premium_access → anexe os produtos
• Offerings → + New → crie default → adicione os produtos

4. Configurar no projetoCopiar link da âncora

Se for um projeto novo, a CLI pede a chave durante o kasy new.

Em projeto existente:

kasy add revenuecat

Ou edite o .env diretamente:

RC_TEST_KEY=test_xxxxxxxxxxxxxxx

5. Rodar e testarCopiar link da âncora

kasy run     # simulador iOS ou emulador Android

Um modal de compra simulada aparece com 3 opções: Sucesso / Erro / Cancelado. Escolha Sucesso: o entitlement deve ativar e o app liberar o conteúdo premium.

Webhook keyCopiar link da âncora

A chave do webhook (rc_wh_...) precisa ser idêntica no backend e no painel do RevenueCat (campo Authorization header value). A função compara a string inteira do header, incluindo o prefixo Bearer .

No modo Rápido do kasy new, o módulo RevenueCat já vem instalado, mas as credenciais não: o prompt da chave só aparece no fluxo interativo (não Rápido). Configure depois com kasy configure, configure_project_keys no MCP ou kasy deploy.

Backend:

1. Gravar o secret: kasy configure / configure_project_keys com RC_WEBHOOK_KEY, ou kasy deploy (quando a chave já estiver no fluxo). No Supabase o secret se chama REVENUECAT_WEBHOOK_KEY; a CLI grava com o prefixo Bearer .
2. RevenueCat → Project → Integrations → Webhooks → campo "Authorization header value": cole Bearer + a mesma chave (ex.: Bearer rc_wh_abc123).

Para ver ou alterar depois:

# Firebase: ver valor atual
firebase functions:secrets:access REVENUECAT_WEBHOOK_KEY

# Supabase: alterar valor (inclua Bearer, a função compara a string inteira)
supabase secrets set REVENUECAT_WEBHOOK_KEY="Bearer rc_wh_..."

Se os dois lados não tiverem o mesmo valor, o webhook retorna 401 e a tabela subscriptions para de atualizar.

Para testar: no painel RC, depois de salvar o webhook, clique em Send test event. Se a resposta for 200 OK, está funcionando. Depois faça uma compra pelo Test Store e confira se a linha aparece na tabela subscriptions.

Fase 2: Sandbox real (iOS)Copiar link da âncora

Necessário quando o fluxo via Test Store já funciona e você quer testar com produto real na App Store.

Custo: USD $99/ano (conta Apple Developer)

1. Criar conta Apple DeveloperCopiar link da âncora

Acesse developer.apple.com e pague o USD $99/ano.

2. Configurar a parte comercial no App Store ConnectCopiar link da âncora

Sem isso o Sandbox não funciona. App Store Connect → menu superior → Agreements, Tax, and Banking:

• Assine o Paid Applications Agreement
• Cadastre e valide a conta bancária
• Preencha os formulários fiscais

Aguarde aprovação (pode levar até 1 dia).

3. Criar o app no App Store ConnectCopiar link da âncora

App Store Connect → My Apps → + → New App → use o mesmo Bundle ID do projeto Flutter.

4. Criar as assinaturasCopiar link da âncora

App Store Connect → seu app → Monetização → Assinaturas:

• Crie um grupo de assinaturas (ex: "Premium")
• Adicione os produtos (ex: premium_monthly, premium_annual)
• O identificador deve ser idêntico ao que você vai criar no RevenueCat

5. Configurar o RevenueCat com a chave AppleCopiar link da âncora

No painel RC → Project → Apps → + Add app → App Store → copie a chave appl_xxx.

Cole no .env:

RC_IOS_PROD_KEY=appl_xxxxxxxxxxxxxxx

6. Criar Produtos, Entitlements e Offerings no RCCopiar link da âncora

Com a chave appl_xxx ativa:

• Products → crie com os mesmos IDs das assinaturas do App Store Connect
• Entitlements → premium_access → anexe os produtos
• Offerings → default → adicione os pacotes

7. Criar conta Sandbox TesterCopiar link da âncora

App Store Connect → Users and Access → aba Sandbox → Testers → + → crie com um e-mail fictício.

8. Conectar Sandbox Tester no iPhoneCopiar link da âncora

No iPhone físico: Ajustes → App Store → Sandbox Account → Sign In com o e-mail/senha do Tester criado. Em versões recentes do iOS o campo fica em Ajustes → Desenvolvedor → Sandbox Apple Account (só aparece com o Modo de Desenvolvedor ligado).

9. TestarCopiar link da âncora

kasy run      # detecta iPhone físico e usa RC_IOS_PROD_KEY automaticamente

Faça uma compra: o modal real da Apple aparece. Confirme e o entitlement deve ativar.

Fase 2: Sandbox real (Android)Copiar link da âncora

Custo: USD $25 (pagamento único)

1. Criar conta Google Play DeveloperCopiar link da âncora

Acesse play.google.com/console e pague o USD $25.

2. Configurar Merchant AccountCopiar link da âncora

Google Play Console → Configurações → Conta do desenvolvedor → Perfil de pagamentos → preencha o nome legal e o endereço da empresa. Dados bancários e fiscais não são pedidos nessa etapa, só entram depois, quando a primeira venda acontecer.

3. Criar e publicar no track internoCopiar link da âncora

Gere um APK/AAB assinado e suba em: Testes → Testes internos → criar release → publicar.

O app não precisa estar completo. Uma versão de desenvolvimento assinada já serve. Isso é obrigatório para criar assinaturas.

4. Criar as assinaturasCopiar link da âncora

Google Play Console → seu app → Monetizar → Assinaturas → + Criar assinatura:

• Crie premium_monthly, premium_annual
• O identificador deve ser idêntico ao que você vai criar no RevenueCat

5. Criar Service Account e configurar RCCopiar link da âncora

O Android usa uma Service Account:

a) Google Cloud Console → seu projeto → APIs e serviços → Biblioteca: ative Google Play Android Developer API e Google Play Developer Reporting API

b) IAM e administração → Contas de serviço → + Criar → dê um nome (ex: revenuecat-play) → Criar e fechar (não precisa conceder papéis aqui). Depois abra a conta criada → aba Chaves → Adicionar chave → Criar nova chave → JSON: o download começa automaticamente. Guarde esse arquivo, você vai precisar dele no passo (d).

c) Google Play Console → Usuários e permissões → Convidar usuário → cole o e-mail da service account (nome@seu-projeto.iam.gserviceaccount.com) → permissão de Administrador → Aplicar ao app

d) No painel RC → Apps → + Add app → Google Play → suba o JSON da service account → copie a chave goog_xxx

Cole no .env:

RC_ANDROID_PROD_KEY=goog_xxxxxxxxxxxxxxx

Fase 3: ProduçãoCopiar link da âncora

Use as mesmas chaves da Fase 2. O RevenueCat detecta sozinho se a compra é Sandbox ou Produção. O que muda:

• A chave P8 é obrigatória no RC para iOS (App Settings → In-App Purchase Key)
• Os produtos precisam estar aprovados nas lojas
• Teste via TestFlight antes de submeter (iOS)

InformaçõesCopiar link da âncora

O que a CLI configura automaticamenteCopiar link da âncora

Ao selecionar RevenueCat no kasy new ou kasy add revenuecat:

3 conceitos essenciaisCopiar link da âncora

Fluxo: Produto comprado → Entitlement ativo → app desbloqueia o conteúdo premium

Chaves por tipo de deviceCopiar link da âncora

O RevenueCat usa três tipos de chave, cada uma para um ambiente:

O kasy run detecta o device e injeta a chave certa. No .env:

RC_TEST_KEY=test_xxx
RC_IOS_PROD_KEY=appl_xxx
RC_ANDROID_PROD_KEY=goog_xxx

Se só RC_TEST_KEY estiver preenchida, o kasy run usa ela em qualquer device e avisa. O fluxo de desenvolvimento não quebra.

Período de teste gratuito (trial)Copiar link da âncora

O trial é detectado automaticamente pelo kit. Quando o produto tem um introductoryPrice com price = 0.0, a duração aparece no paywall automaticamente. Você não muda nada no código, só configura nas lojas.

iOS: App Store ConnectCopiar link da âncora

1. App Store Connect → seu app → In-App Purchases
2. Selecione o produto
3. Em "Subscription Prices" → + → Add Introductory Offer
4. Tipo: Free Trial → defina a duração (7 dias, 1 mês etc.)
5. Salve

Android: Google Play ConsoleCopiar link da âncora

1. Google Play Console → Monetizar → Assinaturas
2. Selecione o produto → seção "Free trial"
3. Defina a duração em dias → Salve (pode levar algumas horas para ativar)

Tempo de assinatura no SandboxCopiar link da âncora

Em Sandbox, as assinaturas duram minutos. É normal:

Cada assinatura renova automaticamente até 6 vezes antes de expirar. Se a assinatura "desapareceu" durante o teste, não é bug.

Escolher e trocar o paywallCopiar link da âncora

O kit traz 4 paywalls prontos. No modo Rápido do kasy new, o padrão é o unlock; no Passo a passo, a CLI pergunta qual usar. Os 4 arquivos vão para o projeto de qualquer forma, trocar depois é editar uma linha.

Para trocar, edite o router.dart do seu projeto:

// antes:
child: const PremiumPage(paywall: PaywallFactory.unlock),
// depois:
child: const PremiumPage(paywall: PaywallFactory.solo),

Como o trial funcionaCopiar link da âncora

O toggle liga e desliga o teste grátis do plano anual: ON mostra "X dias grátis, depois o preço"; OFF assina o anual cobrando na hora. É o padrão de Duolingo, Calm e Headspace: o trial remove a barreira do plano mais caro. Se o trial ainda não estiver configurado nas lojas, aparece "0 dias grátis" (esperado em desenvolvimento). Se nenhum produto tiver trial, prefira solo ou compare.

Ver os 4 antes de escolherCopiar link da âncora

Console Admin → Ferramentas → Paywalls mostra os 4 layouts em modo preview, sem compra real. Abra em claro e escuro antes de decidir.

A/B de preços e ofertas (RevenueCat Experiments, todos os backends)Copiar link da âncora

O painel RC → Experiments serve Offerings diferentes para grupos de usuários (ex.: trial de 7 vs 14 dias, preço cheio vs desconto). O código do kit já usa getOfferings().current, então o experimento funciona sem mudar nada no app.

Mudar nome, preço ou produto precisa de nova versão?Copiar link da âncora

Não. O paywall busca tudo das lojas e do painel RC em tempo de execução:

O usuário vê a mudança na próxima abertura do app (cache do SDK). Em desenvolvimento, use hot restart (R): o hot reload (r) não rebusca os dados do RC.

Erros comunsCopiar link da âncora

INVALID_CREDENTIALSCopiar link da âncora

Produtos não aparecem no paywallCopiar link da âncora

• IDs idênticos no App Store Connect/Play Console e no RC, caractere por caractere
• (iOS) Paid Applications Agreement assinado e conta bancária validada; sem isso nada aparece, nem no Sandbox
• (iOS) Produto em Ready to Submit ou Approved
• (Android) App publicado no track interno e conta de pagamento ativa
• Teste em device físico: simulador só funciona com Test Store

Sandbox retorna lista vazia mesmo com a chave certaCopiar link da âncora

Quase sempre é a parte comercial incompleta: (iOS) Agreements, Tax, and Banking pendente; (Android) conta de pagamento não verificada. Esses passos bloqueiam o Sandbox independentemente do RevenueCat.

CustosCopiar link da âncora

MCP do RevenueCatCopiar link da âncora

O RevenueCat tem um servidor MCP que permite criar Produtos, Entitlements, Offerings e paywalls direto pelo Claude, sem abrir o painel.

ConfigurarCopiar link da âncora

Painel RevenueCat → menu superior direito (seu nome) → API Keys → Secret API keys → + New secret API key (começa com sk_).

Cole na sua IA (troque pela sua chave):

Configure o MCP do RevenueCat nesta máquina, no Claude Code.
É um servidor MCP remoto do tipo HTTP na URL https://mcp.revenuecat.ai/mcp
com o header:  Authorization: Bearer MINHA_CHAVE
Minha chave secreta é: sk_XXXXXXXX
Adicione como um servidor MCP chamado "revenuecat".
No fim, me avise pra eu reiniciar o Claude Code.

Reinicie o Claude Code. O MCP só carrega em sessão nova.

Se preferir configurar na mão, adicione no arquivo de configuração MCP do Claude (~/.claude.json ou equivalente):

{
  "mcpServers": {
    "revenuecat": {
      "type": "http",
      "url": "https://mcp.revenuecat.ai/mcp",
      "headers": {
        "Authorization": "Bearer SUA_SK_AQUI"
      }
    }
  }
}

O que dá pra fazerCopiar link da âncora

• "Crie um produto premium_monthly no projeto X"
• "Crie um Offering default e anexe os produtos A e B"
• "Liste todos os Entitlements do meu projeto"
• "Mostre as métricas de receita do último mês"

Atualizado em 03/11/2026