SubSovereign su Web & React Native — guida all’integrazione

Questa guida illustra l’SDK JavaScript/TypeScript, che funziona in tre contesti con una sola libreria: React Native (iOS + Android), React Native TV e il web (con Stripe). Trasforma la tua app da “non so chi mi ha pagato” a “sblocco le funzionalità giuste per l’utente giusto, verificato sul mio server”.

Cosa fa SubSovereign per te

I tuoi utenti si abbonano tramite app store (Apple, Google) o, sul web, tramite Stripe. SubSovereign risponde in modo affidabile a una sola domanda per la tua app: cosa ha effettivamente pagato questo utente?

• La tua app chiede a SubSovereign l’entitlement dell’utente — l’accesso che ha sbloccato.
• La validazione della ricevuta avviene lato server, direttamente con lo store (o Stripe), quindi un client manomesso non può falsificare un abbonamento.
• Il paywall è configurato da remoto, quindi puoi modificare prezzi, prove gratuite e testi senza ridistribuire l’app.
• È self-hosted: gira sulla tua infrastruttura, i dati degli utenti restano con te e non c’è alcuna percentuale sul ricavo — trattieni il 100% di ciò che pagano gli utenti.

Non fidarti mai del client. Il client chiede; il server decide.

Prima di iniziare

Ti serviranno un server SubSovereign in esecuzione, un’app registrata nel dashboard (che ti fornirà un appId e una chiave API), e i tuoi livelli di accesso (tiers, ad esempio pro) creati e collegati ai prodotti che gli utenti acquistano — prodotti dell’App Store / Google Play per React Native, o prezzi Stripe per il web. Gestisci tu stesso l’acquisto (con le librerie di acquisti in-app su React Native, Stripe Checkout/Billing sul web); SubSovereign verifica e registra l’acquisto in seguito.

Passo 1 — Installa l’SDK

npm install @subsovereign/js-sdk

import SubSovereign from '@subsovereign/js-sdk';

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

SubSovereign.configure({
  apiKey:  'YOUR_APP_API_KEY',                  // dal dashboard
  appId:   'your-app-id',                       // dal dashboard
  baseUrl: 'https://subs.tuodominio.com/api/v1', // IL TUO server self-hosted
  userId:  currentUser.id,                      // il tuo ID utente stabile
  locale:  'it',                                // la lingua dell’utente
});

Usa un userId stabile per l’utente autenticato — lo stesso valore ovunque, così l’accesso lo segue tra dispositivi e piattaforme. Riesegui configure se un utente diverso si autentica.

Passo 3 — Verifica cosa può fare l’utente

L’immagine completa arriva da checkEntitlements():

try {
  const result = await SubSovereign.checkEntitlements();
  if (result.hasAccess) sbloccaFunzionalitàPro();
  else mostraEsperienzaGratuita();
} catch (err) {
  // Mantieni l’utente sul suo ultimo accesso noto e riprova dopo.
  console.warn('Controllo entitlement fallito:', err);
}

Per un semplice controllo esiste un helper di comodo, hasAccess(), che fallisce in modo sicuro (restituisce false) in caso di errore di rete, così un problema temporaneo non sblocca mai inavvertitamente le funzionalità a pagamento:

if (await SubSovereign.hasAccess('pro')) sbloccaFunzionalitàPro();

Ogni entitlement in result.entitlements include accessLevelId, isActive, expiresAt, willRenew e il suo store. result.fromCache è true se la risposta proviene dall’ultima cache nota durante un’interruzione breve.

Passo 4 — Vendi un abbonamento

Mostra il paywall

const paywall = await SubSovereign.getPaywallConfig('web'); // oppure 'ios' | 'android' | 'firetv' | 'roku'
if (paywall) renderizzaPaywall(paywall);   // titolo, funzionalità, prodotti…
else renderizzaPaywallAlternativo();

Completa l’acquisto, poi verificalo

Esegui l’acquisto nel modo consueto per la piattaforma, poi passa il risultato a SubSovereign affinché il server lo validi e conceda il livello di accesso. Scegli la chiamata corrispondente a dove è avvenuto l’acquisto:

// Web (Stripe)
await SubSovereign.validateStripeSubscription({
  subscriptionId, productId, accessLevelId: 'pro',
});

// React Native — iOS (StoreKit)
await SubSovereign.validateApplePurchase({ transactionId, productId, accessLevelId: 'pro' });

// React Native — Android (Play Billing)
await SubSovereign.validateGooglePurchase({ purchaseToken, productId, accessLevelId: 'pro' });

Ognuna restituisce true una volta che il server ha confermato l’acquisto. Riesegui checkEntitlements() in seguito e sblocca.

Feature flag

Distribuisci funzionalità da remoto senza ridistribuire:

const flags = await SubSovereign.getFeatureFlags(); // { newPlayer: true, ... }
if (flags.newPlayer) mostraNuovoGiocatore();

Passo 5 — Privacy: GDPR e CCPA

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

await SubSovereign.requestErasure();            // "cancellami"
const mieiDati = await SubSovereign.exportMyData(); // esporta dati
await SubSovereign.setDoNotSell(true);          // segnale "Do Not Sell" CCPA / GPC

Gestione degli errori

checkEntitlements e le chiamate validate… sollevano eccezioni in caso di errore — avvolgile in try/catch e, in caso di errore, mantieni l’utente sul suo ultimo accesso noto e riprova dopo; non bloccare mai un utente pagante a causa di un problema temporaneo. Gli helper di comodo (hasAccess, getPaywallConfig, getFeatureFlags) invece falliscono in modo sicuro, restituendo false/null/{}, quindi sono sicuri da chiamare inline.

Best practice

• Controlla all’avvio per garantire che il blocco sia attivo prima che l’utente raggiunga una funzionalità protetta.
• Ricontrolla dopo un acquisto per aggiornare immediatamente l’interfaccia.
• Non fidarti mai del client — chiedi al server; è lui che ha verificato la ricevuta.
• Un solo userId per utente reale, mantenuto stabile tra web e mobile.

Riferimento rapido

Prossimi passi

• Le piattaforme native hanno le loro guide: Android, iOS, Roku.
• Vuoi approfondire i concetti? Leggi Come funziona SubSovereign.