SubSovereign en Flutter — guía de integración

Esta guía cubre el paquete subsovereign para Flutter (sdk-flutter/) — un cliente de datos y un widget nativo de muro de pago. El muro de pago que diseñas en el panel de control de SubSovereign se renderiza aquí como un widget Flutter Paywall real, usando la misma configuración que los SDK de iOS, Android, web, React y React Native.

Antes de empezar

Necesitarás un servidor SubSovereign en ejecución, una app registrada en el panel (un appId y una clave API de rol SDK), niveles de acceso (por ejemplo, pro) vinculados a tus productos de tienda, y un muro de pago publicado. Gestiona la compra en sí con tu plugin de facturación habitual (por ejemplo, in_app_purchase); SubSovereign verificará y registrará la compra después.

Paso 1 — Instalar

Añade el paquete (ruta/dependencia git mientras esté en fase pre-pub.dev):

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

import 'package:subsovereign/subsovereign.dart';

Paso 2 — Configurar una sola vez, al iniciar la app

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',
));

Usa un userId estable — el mismo valor en todas partes, para que el acceso siga al usuario entre dispositivos.

Paso 3 — Comprobar qué puede acceder el usuario

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');
}

Paso 4 — Mostrar el muro de pago y vender

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

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

Tras el éxito de la compra, haz que el servidor la verifique, luego vuelve a comprobar y desbloquea:

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();
}

Privacidad (GDPR)

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

Botón de desistimiento (UE) (Pasaporte de cumplimiento)

Si vendes suscripciones a consumidores de la UE en línea, la Directiva (UE) 2023/2673 exige un función de desistimiento claramente etiquetada:

WithdrawalButton(subscriptionId: sub.id)

Muestra el botón destacado, confirma una vez y envía de forma idempotente (un reintento de red nunca creará dos desistimientos). Para interfaces personalizadas usa SubSovereign.instance.withdraw(subscriptionId: …) y getWithdrawalConfig().

Referencia rápida

Pasos siguientes

• Un ejemplo ejecutable está en sdk-flutter/example/.
• ¿Nuevos en los conceptos? Lee Cómo funciona SubSovereign.