SubSovereign op Web & React Native — integratiehandleiding

Deze handleiding behandelt de JavaScript/TypeScript SDK, die met één bibliotheek werkt op drie platforms: React Native (iOS + Android), React Native TV en de web (met Stripe). Het brengt je app van "Ik weet niet wie er voor me betaald heeft" naar "mijn app ontgrendelt de juiste functies voor de juiste gebruiker, geverifieerd op mijn eigen server."

Wat SubSovereign voor je doet

Je gebruikers abonneren zich via een app store (Apple, Google) of, op het web, via Stripe. SubSovereign beantwoordt één vraag voor je app, betrouwbaar: waar heeft deze gebruiker precies voor betaald?

• Je app vraagt SubSovereign naar de gebruiksrechten van de gebruiker — de toegang die ze hebben gekregen.
• De server-side ontvangstvalidatie vindt plaats op de server, direct bij de store (of Stripe), zodat een gemanipuleerde client geen abonnement kan vervalsen.
• De paywall is extern configureerbaar, zodat je prijzen, proefperiodes en teksten kunt aanpassen zonder een nieuwe release.
• Het is zelfgehost: het draait op jouw infrastructuur, de gegevens van je gebruikers blijven bij jou, en er is geen inkomensdeling — je houdt 100% van wat je gebruikers betalen.

Je vertrouwt de client nooit. De client vraagt; de server beslist.

Voordat je begint

Je hebt een draaiende SubSovereign-server nodig, een app geregistreerd in het dashboard (waarmee je een appId en een API-sleutel krijgt), en je toegangsniveaus (tiers, bijv. pro) aangemaakt en gekoppeld aan de producten die je gebruikers kopen — App Store-/Google Play-producten voor React Native, of Stripe-prijzen voor het web. De aankoop zelf regel je zoals normaal (in-app aankoopbibliotheken op React Native, Stripe Checkout/Billing op het web); SubSovereign verifieert en registreert deze daarna.

Stap 1 — Installeer de SDK

npm install @subsovereign/js-sdk

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

Stap 2 — Configureer eenmalig bij het opstarten van je app

SubSovereign.configure({
  apiKey:  'YOUR_APP_API_KEY',                  // uit het dashboard
  appId:   'your-app-id',                       // uit het dashboard
  baseUrl: 'https://subs.yourdomain.com/api/v1', // JOUW zelfgehoste server
  userId:  currentUser.id,                      // je eigen stabiele gebruikers-id
  locale:  'nl',                                // de taal van de gebruiker
});

Gebruik een stabiele userId voor de ingelogde gebruiker — dezelfde waarde overal, zodat toegang meegaat over apparaten en platforms. Voer configure opnieuw uit als een andere gebruiker inlogt.

Stap 3 — Controleer waartoe de gebruiker toegang heeft

Het volledige overzicht komt van checkGebruiksrechten():

try {
  const result = await SubSovereign.checkGebruiksrechten();
  if (result.heeftToegang) ontgrendelProFuncties();
  else toonGratisErvaring();
} catch (err) {
  // Houd de gebruiker op zijn laatst bekende toegang en probeer het later opnieuw.
  console.warn('Controle op gebruiksrechten mislukt:', err);
}

Voor een eenvoudige toegangspoort is er een handige helper, heeftToegang(), die gesloten faalt (retourneert false) bij een netwerkfout, zodat een storing nooit per ongeluk betaalde functies ontgrendelt:

if (await SubSovereign.heeftToegang('pro')) ontgrendelProFuncties();

Elke gebruiksrecht in result.gebruiksrechten bevat toegangsNiveauId, isActief, verlooptOp, wordtVerlengd en de winkel. result.uitCache is true als het antwoord afkomstig is uit de laatst bekende cache tijdens een korte storing.

Stap 4 — Verkoop een abonnement

Toon de paywall

const paywall = await SubSovereign.getPaywallConfig('web'); // of 'ios' | 'android' | 'firetv' | 'roku'
if (paywall) renderPaywall(paywall);   // kop, functies, producten…
else renderFallbackPaywall();

Voltooi de aankoop, valideer deze vervolgens

Voer de aankoop uit zoals gebruikelijk voor het platform, geef het resultaat daarna door aan SubSovereign zodat de server het valideert en het toegangsniveau verleent. Kies de aanroep die past bij waar de aankoop plaatsvond:

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

Elk retourneert true zodra de server de aankoop heeft bevestigd. Voer daarna checkGebruiksrechten() opnieuw uit en ontgrendel.

Feature flags

Rol functies uit vanaf de server zonder een nieuwe release:

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

Stap 5 — Privacy: GDPR en CCPA

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

await SubSovereign.requestWissen();            // "vergeet me"
const mijnGegevens = await SubSovereign.exportMijnGegevens(); // gegevensexport
await SubSovereign.setVerkoopNietToestaan(true);          // CCPA "Do Not Sell" / GPC-signaal

Foutafhandeling

checkGebruiksrechten en de validate…-aanroepen gooien bij falen — wikkel ze in try/catch en houd de gebruiker bij een fout op zijn laatst bekende toegang; sluit nooit een betalende gebruiker uit door een storing. De handige helpers (heeftToegang, getPaywallConfig, getFeatureFlags) falen daarentegen gesloten, retourneren false/null/{}, zodat ze veilig inline kunnen worden aangeroepen.

Beste praktijken

• Controleer bij mount / opstart zodat de toegangspoort juist is voor de gebruiker een geblokkeerde functie bereikt.
• Controleer opnieuw na een aankoop zodat de UI direct wordt bijgewerkt.
• Vertrouw de client nooit — vraag de server; die heeft de ontvangst geverifieerd.
• Één userId per echte gebruiker, stabiel over web en mobiel.

Snelle referentie

Volgende stappen

• Native platforms hebben hun eigen handleidingen: Android, iOS, Roku.
• Nieuw voor de concepten? Lees Hoe SubSovereign werkt.