SubSovereign em Flutter — guia de integração

Este guia abrange o pacote Flutter subsovereign (sdk-flutter/) — um cliente de dados e um widget nativo de paywall. O paywall que projetar no painel de controlo do SubSovereign é renderizado aqui como um widget Flutter Paywall, a partir da mesma configuração dos SDKs para iOS, Android, web, React e React Native.

Antes de começar

É necessário um servidor SubSovereign em execução, um app registado no painel (um appId e uma chave de API com função de SDK), níveis de acesso (ex. pro) associados aos seus produtos na loja, e um paywall publicado. Gerencie a compra com o seu plugin de faturação habitual (ex. in_app_purchase); o SubSovereign verifica e regista a compra depois.

Passo 1 — Instalar

Adicione o pacote (dependência por caminho/repositório enquanto não estiver disponível no pub.dev):

dependencies:
  subsovereign:
    path: ../sdk-flutter   # or a git dependency

import 'package:subsovereign/subsovereign.dart';

Passo 2 — Configurar uma vez, quando o app iniciar

SubSovereign.instance.configure(SubSovereignConfig(
  apiKey:  'YOUR_SDK_KEY',
  appId:   'your-app-id',
  baseUrl: 'https://subs.yourdomain.com/api/v1', // YOUR self-hosted server
  userId:  currentUser.id,                        // your own stable user id
  locale:  'en',
));

Use um userId estável — o mesmo valor em todos os locais, para que o acesso acompanhe o utilizador entre dispositivos.

Passo 3 — Verificar o que o utilizador pode aceder

try {
  final result = await SubSovereign.instance.checkEntitlements();
  if (result.hasAccess) {
    showPremiumContent();
  } else {
    showPaywall();
  }
} on SubSovereignException catch (e) {
  // Keep the user on their last-known access and retry later.
  debugPrint('Entitlement check failed: $e');
}

Passo 4 — Mostrar o paywall e vender

final config = await SubSovereign.instance.getPaywallConfig(platform: 'android');

Paywall(
  config: config,
  onSelectProduct: (productId) => buy(productId), // your billing plugin
)

Após a compra ser bem-sucedida, peça ao servidor para a verificar, depois volte a verificar e desbloqueie:

final granted = await SubSovereign.instance.validateGooglePurchase(
  purchaseToken: purchase.verificationData.serverVerificationData,
  productId: purchase.productID,
  accessLevelId: 'pro',
);
if (granted) {
  final result = await SubSovereign.instance.checkEntitlements();
  if (result.hasAccess) unlockProFeatures();
}

Privacidade (RGPD)

await SubSovereign.instance.recordConsent(purpose: 'analytics', granted: true);

Botão de desistência (UE) (Passaporte de Conformidade)

Se vender assinaturas a consumidores da UE online, a Diretiva (UE) 2023/2673 exige um botão de desistência claramente identificado:

WithdrawalButton(subscriptionId: sub.id)

Ele mostra o botão proeminente, confirma uma vez e envia de forma idempotente (uma nova tentativa de rede nunca criará duas desistências). Para interfaces personalizadas, use SubSovereign.instance.withdraw(subscriptionId: …) e getWithdrawalConfig().

Referência rápida

Próximos passos

• Um exemplo executável está em sdk-flutter/example/.
• Se é novo nestes conceitos, leia Como funciona o SubSovereign.