SubSovereign su Flutter — guida all’integrazione

Questa guida copre il pacchetto Flutter subsovereign (sdk-flutter/) — un client dati e un widget nativo per paywall. Il paywall che progetti nella dashboard di SubSovereign viene renderizzato qui come un vero widget Flutter Paywall, partendo dalla stessa configurazione usata per gli SDK di iOS, Android, web, React e React Native.

Prima di iniziare

È necessario un server SubSovereign in esecuzione, un’app registrata nella dashboard (un appId e una chiave API per il ruolo SDK), livelli di accesso (ad esempio pro) collegati ai tuoi prodotti dello store e un paywall pubblicato. Gestisci l’acquisto vero e proprio con il tuo solito plugin di fatturazione (ad esempio in_app_purchase); SubSovereign verifica e registra l’acquisto in seguito.

Passo 1 — Installazione

Aggiungi il pacchetto (percorso/dipendenza Git finché non è disponibile su pub.dev):

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

import 'package:subsovereign/subsovereign.dart';

Passo 2 — Configurazione una volta sola, all’avvio dell’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 stabile — lo stesso valore ovunque, in modo che l’accesso segua l’utente tra i dispositivi.

Passo 3 — Verifica cosa può fare l’utente

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 — Mostra il paywall e vendi

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

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

Dopo il successo dell’acquisto, fai verificare l’acquisto dal server, quindi ricontrolla e sblocca:

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

Privacy (GDPR)

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

Pulsante di recesso UE (Compliance Passport)

Se vendi abbonamenti a consumatori UE online, la Direttiva (UE) 2023/2673 richiede una funzione di recesso chiaramente etichettata:

WithdrawalButton(subscriptionId: sub.id)

Mostra il pulsante in evidenza, conferma una volta e invia in modo idempotente (un nuovo tentativo di rete non può creare due recessi). Per interfacce utente personalizzate usa SubSovereign.instance.withdraw(subscriptionId: …) e getWithdrawalConfig().

Riferimento rapido

Passaggi successivi

• Un esempio eseguibile si trova in sdk-flutter/example/.
• Nuovo ai concetti? Leggi Come funziona SubSovereign.