SubSovereign per React Native — guida all’integrazione

Questa guida copre @subsovereign/react-native (sdk-react-native/) — un client dati e un renderer nativo per la paywall in un unico pacchetto. La paywall che progetti nel dashboard di SubSovereign viene resa qui con primitive native di React Native (View/Text/Pressable), partendo dalla stessa configurazione utilizzata dagli SDK per iOS, Android, web, React e Flutter.

Stai già usando @subsovereign/js-sdk in React Native? Funziona ugualmente (vedi la guida per Web e React Native) — questo pacchetto aggiunge il componente nativo <Paywall> e un client dati senza dipendenze native (solo fetch puro).

Prima di iniziare

Un server SubSovereign in esecuzione, un’app registrata nel dashboard (un appId e una chiave API con ruolo SDK), livelli di accesso (ad esempio pro) collegati ai tuoi prodotti dello store e una paywall pubblicata.

Passo 1 — Installazione

Il pacchetto si trova in sdk-react-native/ ed è attualmente disponibile solo come dipendenza locale o da repository Git — aggiungilo come dipendenza da percorso o Git (oppure copia la cartella nel tuo progetto):

npm install ./sdk-react-native   # path dependency while it's pre-npm

Funzionalità opzionali, utilizzate automaticamente se presenti (mai dipendenze hard):

npx expo install expo-linear-gradient   # gradient paywall backgrounds
npm install react-native-video          # hero video (falls back to image without it)

Passo 2 — Configura una volta, all’avvio dell’app

import { SubSovereign } from '@subsovereign/react-native';

SubSovereign.configure({
  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',
});

Passo 3 — Verifica cosa può fare l’utente

const result = await SubSovereign.checkEntitlements();
if (result.hasAccess) showPremiumContent();
else showPaywall();

Avvolgilo in un try/catch; in caso di errore, mantieni l’accesso noto dell’utente e riprova più tardi — non bloccare mai un utente pagante per un problema di rete.

Passo 4 — Mostra la paywall e vendi

import { Paywall, usePaywallConfig } from '@subsovereign/react-native';
import { Platform } from 'react-native';

const config = await SubSovereign.getPaywallConfig(Platform.OS); // or usePaywallConfig(params)

<Paywall config={config} onSelectProduct={(productId) => buy(productId)} />

Esegui l’acquisto con la tua libreria di billing come al solito, quindi fai verificare l’acquisto sul server:

// Android (Play Billing) — built into this client:
await SubSovereign.validateGooglePurchase({ purchaseToken, productId, accessLevelId: 'pro' });

// iOS (StoreKit): use the Web/JS data SDK's validateApplePurchase —
// this client does not ship an Apple call. See web.en.md Step 4.

Esegui nuovamente checkEntitlements() dopo e sblocca l’accesso.

Privacy (GDPR)

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

Pulsante di recesso UE (Compliance Passport)

import { WithdrawalButton } from '@subsovereign/react-native';

<WithdrawalButton subscriptionId={sub.id} />

Mostra il pulsante etichettato in modo prominente, conferma una volta e invia in modo idempotente. Nota: questo pulsante non recupera la configurazione di recesso dell’app — se disabiliti o limiti giurisdizionalmente i recessi nel dashboard, gestisci tu stesso la visibilità con SubSovereign.getWithdrawalConfig(). È disponibile anche SubSovereign.withdraw(subscriptionId, opts) per interfacce utente personalizzate (passa channel: Platform.OS).

Riferimento rapido

Passaggi successivi

• Approfondimento completo sul livello dati (flag, cancellazione, esportazione): guida per Web e React Native.
• Nuovo ai concetti? Leggi Come funziona SubSovereign.