SubSovereign sur Web & React Native — guide d'intégration

Ce guide couvre le SDK JavaScript/TypeScript, qui fonctionne dans trois environnements à partir d’une seule bibliothèque : React Native (iOS + Android), React Native TV et le web (avec Stripe). Il transforme votre application, passant de « Je ne sais pas qui m’a payé » à « mon application débloque les bonnes fonctionnalités pour le bon utilisateur, vérifié sur mon propre serveur ».

Ce que SubSovereign fait pour vous

Vos utilisateurs s’abonnent via une boutique d’applications (Apple, Google) ou, sur le web, via Stripe. SubSovereign répond de manière fiable à une seule question pour votre application : que cet utilisateur a-t-il réellement payé ?

• Votre application demande à SubSovereign les droits d’accès de l’utilisateur — l’accès qu’il a débloqué.
• La validation des reçus s’effectue côté serveur, directement auprès de la boutique (ou de Stripe), afin qu’un client falsifié ne puisse pas simuler un abonnement.
• Le mur de paiement est configuré à distance, ce qui vous permet de modifier les prix, les essais et le texte sans redéployer l’application.
• Il est auto-hébergé : il s’exécute sur votre infrastructure, les données de vos utilisateurs restent chez vous, et il n’y a aucun partage de revenus — vous conservez 100 % de ce que vos utilisateurs paient.

Vous ne faites jamais confiance au client. Le client pose la question ; le serveur décide.

Avant de commencer

Vous aurez besoin d’un serveur SubSovereign en cours d’exécution, d’une application enregistrée dans le tableau de bord (vous donnant un appId et une clé API), ainsi que de vos niveaux d’accès (tiers, par exemple pro) créés et associés aux produits que vos utilisateurs achètent — produits de l’App Store / Google Play pour React Native, ou prix Stripe pour le web. Gérez l’achat lui-même comme vous le feriez normalement (bibliothèques d’achats intégrés sur React Native, Stripe Checkout/Billing sur le web) ; SubSovereign le vérifie et l’enregistre ensuite.

Étape 1 — Installer le SDK

npm install @subsovereign/js-sdk

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

Étape 2 — Configurer une fois, au démarrage de l’application

SubSovereign.configure({
  apiKey:  'YOUR_APP_API_KEY',                  // depuis le tableau de bord
  appId:   'your-app-id',                       // depuis le tableau de bord
  baseUrl: 'https://subs.yourdomain.com/api/v1', // VOTRE serveur auto-hébergé
  userId:  currentUser.id,                      // votre propre identifiant utilisateur stable
  locale:  'fr',                                // la langue de l’utilisateur
});

Utilisez un userId stable pour l’utilisateur connecté — la même valeur partout, afin que l’accès le suive sur tous les appareils et plateformes. Relancez configure si un autre utilisateur se connecte.

Étape 3 — Vérifier ce à quoi l’utilisateur peut accéder

L’image complète provient de checkEntitlements() :

try {
  const result = await SubSovereign.checkEntitlements();
  if (result.hasAccess) unlockProFeatures();
  else showFreeExperience();
} catch (err) {
  // Maintenez l’utilisateur sur son dernier accès connu et réessayez plus tard.
  console.warn('Échec de la vérification des droits d’accès :', err);
}

Pour une vérification simple, il existe un helper pratique, hasAccess(), qui échoue en mode sécurisé (renvoie false) en cas d’erreur réseau afin qu’une panne ne débloque jamais accidentellement des fonctionnalités payantes :

if (await SubSovereign.hasAccess('pro')) unlockProFeatures();

Chaque droit d’accès dans result.entitlements contient accessLevelId, isActive, expiresAt, willRenew et son store. result.fromCache vaut true si la réponse provient du cache connu lors d’une brève interruption.

Étape 4 — Vendre un abonnement

Afficher le mur de paiement

const paywall = await SubSovereign.getPaywallConfig('web'); // ou 'ios' | 'android' | 'firetv' | 'roku'
if (paywall) renderPaywall(paywall);   // titre, fonctionnalités, produits…
else renderFallbackPaywall();

Finaliser l’achat, puis le vérifier

Effectuez l’achat de la manière habituelle pour la plateforme, puis transmettez le résultat à SubSovereign afin que le serveur valide l’achat et accorde le niveau d’accès. Choisissez l’appel correspondant à l’endroit où l’achat a eu lieu :

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

Chaque appel renvoie true une fois que le serveur a confirmé l’achat. Relancez checkEntitlements() ensuite et débloquez l’accès.

Drapeaux de fonctionnalités

Déployez des fonctionnalités depuis le serveur sans redéployer l’application :

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

Étape 5 — Confidentialité : RGPD et CCPA

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

await SubSovereign.requestErasure();            // "oubliez-moi"
const myData = await SubSovereign.exportMyData(); // export des données
await SubSovereign.setDoNotSell(true);          // signal "Ne pas vendre" RGPD/CCPA

Gestion des erreurs

Les appels checkEntitlements et validate… lèvent une exception en cas d’échec — enveloppez-les dans un try/catch et, en cas d’erreur, maintenez l’utilisateur sur son dernier accès connu et réessayez plus tard ; ne bloquez jamais un utilisateur payant à cause d’une panne. Les helpers pratiques (hasAccess, getPaywallConfig, getFeatureFlags) échouent en mode sécurisé, renvoyant false/null/{}, ce qui les rend sûrs à appeler en ligne.

Bonnes pratiques

• Vérifiez au montage / au lancement afin que le contrôle d’accès soit juste avant que l’utilisateur n’atteigne une fonctionnalité verrouillée.
• Relancez la vérification après un achat afin que l’interface se mette à jour immédiatement.
• Ne faites jamais confiance au client — demandez au serveur ; c’est lui qui a vérifié le reçu.
• Un seul userId par utilisateur réel, maintenu stable entre le web et le mobile.

Référence rapide

Prochaines étapes

• Les plateformes natives ont leurs propres guides : Android, iOS, Roku.
• Vous débutez avec ces concepts ? Lisez Comment fonctionne SubSovereign.