andrelucassvt/.claude/skills/implement-in-app-purchase

Implement In-App Purchase — Flutter

Implementa o fluxo completo de In-App Purchase seguindo a arquitetura do projeto.

Leitura Rápida

• Primeiro passo obrigatório: faça TODAS as perguntas ao usuário (Passo 1) antes de gerar qualquer código.
• Modo sem back-end: InAppPurchaseService + StorageService — sem Repository ou DataSource.
• Modo com back-end: adiciona Entity + Repository Interface + Model + DataSource + RepositoryImpl.
• Verificação: completePurchase() NUNCA é chamado antes da verificação — local ou server-side.
• Stream: o resultado da compra SEMPRE vem pelo purchaseStream — nunca emita PurchaseSuccess direto no buyProduct().
• Cubit: cancele _purchaseSubscription no close() — nunca deixe o stream vazar.
• Apple Guideline 3.1.2(c): telas de paywall com assinatura DEVEM exibir links de Termos de Uso e Política de Privacidade.
• Segurança: nunca confie apenas na validação client-side para desbloquear conteúdo premium.

---

Passo 1 — Perguntas obrigatórias ao usuário

Antes de gerar qualquer código, faça TODAS as perguntas abaixo em uma única mensagem usando o vscode_askQuestions tool (ou liste claramente e aguarde resposta):

1. O app tem back-end próprio?
   - SIM → o back-end valida e registra as compras
   - NÃO → verificação ocorre 100% localmente no dispositivo

2. Quais tipos de produto você precisa implementar?
   - [ ] Consumível (ex: pacotes de créditos, tokens)
   - [ ] Assinatura (ex: plano mensal/anual)
   - [ ] Não-consumível permanente (ex: remover anúncios)

3. Quais são os IDs dos produtos cadastrados nas lojas?
   (App Store Connect e Google Play Console)
   Ex: "basic_1", "pro_pack", "premium_monthly"

4. Qual é o nome da feature/tela onde ficará a lógica de compra?
   Ex: "purchase", "paywall", "subscription"

Guarde as respostas para guiar toda a implementação.

---

Passo 2 — Determinar a arquitetura de verificação

Com base na resposta sobre back-end, siga um dos dois caminhos:

🅰️ SEM back-end (verificação local)

Arquitetura:

View → Cubit → InAppPurchaseService → App Store / Google Play
                      ↑                        ↓
               purchaseStream          PurchaseDetails
                      ↓
       verifyPurchase / verifySubscription (VerifyLocalPurchase)
                      ↓
       StorageService.setString('purchase_<productId>', verificationData)

No InAppPurchaseService, após verificação bem-sucedida:

• Salve purchase.verificationData.localVerificationData via StorageService
• Salve também purchase.verificationData.source para identificar a plataforma
• Use chaves consistentes: 'purchase_receipt_<productId>'

Exemplo no service:

Future<bool> verifyPurchase(
  PurchaseDetails purchase,
  StorageService storage,
) async {
  final token = getOneTimePurchaseToken(purchase);
  final isValid = await VerifyLocalPurchase().verifyPurchase(token);
  if (isValid) {
    await storage.setString(
      'purchase_receipt_${purchase.productID}',
      purchase.verificationData.localVerificationData,
    );
    await storage.setString(
      'purchase_source_${purchase.productID}',
      purchase.verificationData.source,
    );
    await _iap.completePurchase(purchase);
  }
  return isValid;
}

Future<bool> verifySubscription(
  PurchaseDetails purchase,
  StorageService storage,
) async {
  final token = getSubscriptionToken(purchase);
  final isValid = await VerifyLocalPurchase().verifySubscription(token);
  if (isValid) {
    await storage.setString(
      'purchase_receipt_${purchase.productID}',
      purchase.verificationData.localVerificationData,
    );
    await storage.setString(
      'purchase_source_${purchase.productID}',
      purchase.verificationData.source,
    );
    await _iap.completePurchase(purchase);
  }
  return isValid;
}

Dados salvos no StorageService:

| Chave | Valor | Descrição | |---|---|---| | purchase_receipt_<productId> | localVerificationData | Receipt iOS (base64) ou Purchase Token Android | | purchase_source_<productId> | app_store / google_play | Plataforma de origem |

Aviso ao usuário: Informe que os dados de verificação ficam somente no dispositivo — se o usuário reinstalar o app, as compras não-consumíveis/assinaturas precisarão ser restauradas via restorePurchases().

---

🅱️ COM back-end (envio ao servidor)

Arquitetura:

View → Cubit → InAppPurchaseService → App Store / Google Play
                      ↑                        ↓
               purchaseStream          PurchaseDetails
                      ↓
             PurchaseRepository (interface no domain)
                      ↓
          PurchaseRepositoryImpl (data layer)
                      ↓
          PurchaseRemoteDataSource → POST /purchases/verify

Dado enviado ao back-end:

{
  "product_id": purchase.productID,
  "verification_data": purchase.verificationData.serverVerificationData,
  "source": purchase.verificationData.source,           // "app_store" | "google_play"
  "local_verification_data": purchase.verificationData.localVerificationData,
}

Estrutura de arquivos adicionais (apenas no modo com back-end):

domain/
  entities/purchase_entity.dart
  interfaces/purchase_repository.dart

data/
  models/purchase_model.dart
  datasources/purchase_remote_datasource.dart
  repositories/purchase_repository_impl.dart

Interface do Repository:

abstract class PurchaseRepository {
  /// Envia dados de verificação ao back-end e retorna se a compra é válida
  Future<Result<bool>> verifyPurchaseOnServer({
    required String productId,
    required String serverVerificationData,
    required String localVerificationData,
    required String source,
  });
}

No Cubit (modo back-end):

• Receba InAppPurchaseService E PurchaseRepository
• No _processPurchaseUpdates, após receber PurchaseStatus.purchased:
  1. Chame _purchaseRepository.verifyPurchaseOnServer(...) com os dados de verificação
  2. Use result.when(ok: ..., error: ...) para emitir o estado final
  3. Se validado, chame _purchaseService.completePurchase(purchase) manualmente

// Cubit com back-end — trecho do _processPurchaseUpdates
if (purchase.status == PurchaseStatus.purchased ||
    purchase.status == PurchaseStatus.restored) {
  try {
    final result = await _purchaseRepository.verifyPurchaseOnServer(
      productId: purchase.productID,
      serverVerificationData: purchase.verificationData.serverVerificationData,
      localVerificationData: purchase.verificationData.localVerificationData,
      source: purchase.verificationData.source,
    );

    result.when(
      ok: (isValid) async {
        if (isValid) {
          await _purchaseService.completePurchase(purchase);
        }
        emit(PurchaseSuccess(productId: purchase.productID, isValid: isValid));
      },
      error: (e) => emit(PurchaseError('Verificação no servidor falhou: $e')),
    );
  } catch (e) {
    emit(PurchaseError('Erro inesperado: $e'));
  }
}

---

Passo 3 — Arquivos a criar (mínimo obrigatório)

Para AMBOS os modos:

✅ lib/common/services/in_app_purchase/in_app_purchase_service.dart
✅ lib/presentation/<feature>/view_model/<feature>_cubit.dart
✅ lib/presentation/<feature>/view_model/<feature>_state.dart
✅ lib/presentation/<feature>/view/<feature>_view.dart  ← incluir links de Termos de Uso e Privacidade
✅ Registrar InAppPurchaseService (LazySingleton) e Cubit (Factory) em app_injector.dart
✅ Adicionar rota em app_routes.dart e app_router.dart
✅ Inicializar VerifyLocalPurchase em app_initializer.dart
✅ Adicionar strings premiumTermsOfUse e premiumPrivacyPolicy nos arquivos ARB

⚠️ Apple Guideline 3.1.2(c) — obrigatório para assinaturas: A View de paywall DEVE exibir links funcionais para Termos de Uso (EULA) e Política de Privacidade. Use url_launcher com LaunchMode.externalApplication. Exemplo:

import 'package:url_launcher/url_launcher.dart';

Row(
  mainAxisAlignment: MainAxisAlignment.center,
  children: [
    TextButton(
      onPressed: () => launchUrl(
        Uri.parse('https://sua-url/termos'),
        mode: LaunchMode.externalApplication,
      ),
      style: TextButton.styleFrom(
        padding: const EdgeInsets.symmetric(horizontal: 8),
        textStyle: theme.textTheme.bodySmall,
      ),
      child: Text(l10n.premiumTermsOfUse),
    ),
    Text('·', style: theme.textTheme.bodySmall?.copyWith(
      color: theme.colorScheme.onSurface.withValues(alpha: 0.5),
    )),
    TextButton(
      onPressed: () => launchUrl(
        Uri.parse('https://sua-url/privacidade'),
        mode: LaunchMode.externalApplication,
      ),
      style: TextButton.styleFrom(
        padding: const EdgeInsets.symmetric(horizontal: 8),
        textStyle: theme.textTheme.bodySmall,
      ),
      child: Text(l10n.premiumPrivacyPolicy),
    ),
  ],
),

Apenas no modo SEM back-end:

✅ Injetar StorageService no InAppPurchaseService (via construtor)
✅ Salvar dados de verificação com StorageService após compra validada

Apenas no modo COM back-end:

✅ lib/domain/entities/purchase_entity.dart
✅ lib/domain/interfaces/purchase_repository.dart
✅ lib/data/models/purchase_model.dart
✅ lib/data/datasources/purchase_remote_datasource.dart
✅ lib/data/repositories/purchase_repository_impl.dart
✅ Registrar DataSource e Repository em app_injector.dart
✅ Injetar PurchaseRepository no Cubit junto com InAppPurchaseService

---

Passo 4 — Checklist de implementação

Após gerar o código, valide cada item:

Service

• [ ] IDs de produtos declarados como constantes static const
• [ ] _productIds (consumíveis) e _subscriptionIds separados em Sets
• [ ] purchaseStream exposto para o Cubit
• [ ] isSubscriptionProduct(productId) implementado
• [ ] completePurchase() chamado apenas após validação bem-sucedida
• [ ] Sem back-end: StorageService injetado via construtor; dados salvos após verificação
• [ ] Com back-end: não salva localmente; delega ao Repository

Cubit

• [ ] _listenToPurchaseStream() chamado no construtor
• [ ] _purchaseSubscription cancelado no close()
• [ ] PurchaseStatus.pending ignorado (apenas continue)
• [ ] PurchaseStatus.error → emite PurchaseError
• [ ] PurchaseStatus.purchased e restored → verificam e emitem PurchaseSuccess
• [ ] buyProduct() e buySubscription() não emitem PurchaseSuccess diretamente
• [ ] Todos os métodos assíncronos emitem PurchaseLoading primeiro

State (sealed class)

• [ ] @immutable em todos
• [ ] const em todos os construtores
• [ ] Estados: Initial, Loading, ProductsLoaded, SubscriptionsLoaded, Success, Error

View

• [ ] SafeArea envolvendo o conteúdo principal
• [ ] Todos os estados tratados no BlocBuilder
• [ ] Textos via context.l10n.<chave> — zero strings hardcoded
• [ ] _cubit.close() chamado no dispose()
• [ ] _cubit.loadProducts() ou loadSubscriptions() chamado no initState()
• [ ] Links de Termos de Uso e Política de Privacidade presentes na tela de paywall (obrigatório — Apple Guideline 3.1.2(c))
• [ ] url_launcher importado na View para abrir os links
• [ ] Strings premiumTermsOfUse e premiumPrivacyPolicy adicionadas nos arquivos ARB (app_en.arb e app_pt.arb)

DI (app_injector.dart)

• [ ] InAppPurchaseService → registerLazySingleton
• [ ] Sem back-end: StorageService já registrado (reutilizar existente)
• [ ] Com back-end: PurchaseRemoteDataSource → registerLazySingleton; PurchaseRepository → registerLazySingleton
• [ ] PurchaseCubit → registerFactory

AppInitializer

• [ ] VerifyLocalPurchase.initialize(...) chamado antes de setupDependencies
• [ ] useSandbox: flavor != AppFlavor.production no AppleConfig

---

Passo 5 — Aviso de segurança obrigatório

Sempre informe ao usuário:

⚠️ Nunca confie apenas na validação client-side para desbloquear conteúdo premium.

• Sem back-end: a verificação via verify_local_purchase é uma proteção razoável contra fraudes simples, mas não é infalível. Considere migrar para validação server-side no futuro.
• Com back-end: valide SEMPRE no servidor antes de conceder acesso ao conteúdo. Nunca desbloqueie premium apenas com base no retorno do purchaseStream sem passar pelo seu servidor.

---

Passo 6 — Perguntas de IDs e credenciais

Após gerar o código-esqueleto, lembre o usuário de substituir os placeholders:

📋 Substitua no código gerado:
- 'com.example.app'             → Bundle ID / Package Name real do app
- 'your-issuer-id'              → Issuer ID da App Store Connect
- 'your-key-id'                 → Key ID da App Store Connect
- '-----BEGIN PRIVATE KEY-----' → Chave privada da App Store Connect
- '{"type":"service_account"}'  → JSON da conta de serviço do Google Play
- IDs dos produtos               → IDs exatos cadastrados nas lojas

---

Fluxo resumido por tipo de produto

| Tipo | Método de compra | Método de verificação | completePurchase? | |---|---|---|---| | Consumível | buyConsumable | verifyPurchase | ✅ Sim (obrigatório Android) | | Assinatura | buyNonConsumable | verifySubscription | ✅ Sim | | Não-consumível permanente | buyNonConsumable | verifySubscription | ✅ Sim |

---

Anti-patterns a evitar

• ❌ NÃO crie DataSource/Repository para IAP no modo sem back-end
• ❌ NÃO emita PurchaseSuccess direto no buyProduct — o resultado vem pelo stream
• ❌ NÃO acesse InAppPurchaseService diretamente da View
• ❌ NÃO cancele _purchaseSubscription antes do dispose() do Cubit
• ❌ NÃO ignore PurchaseStatus.error
• ❌ NÃO use SharedPreferences diretamente — use sempre StorageService
• ❌ NÃO salve serverVerificationData localmente — use apenas localVerificationData
• ❌ NÃO desbloqueie conteúdo premium sem verificar o receipt (local ou server-side)

---

Última atualização: 28 de março de 2026