SubSovereign
← All guides

Démarrage avec SubSovereign

Ce guide vous accompagne de zéro jusqu’à une vérification d’abonnement fonctionnelle dans votre application. Il complète Fonctionnement de SubSovereign — lisez-le d’abord si vous souhaitez comprendre les concepts.

Il y a cinq étapes : déployer le serveur → créer votre application → définir vos offres → intégrer le SDK → vérifier l’accès. Prévoyez un après-midi pour la première étape ; les autres sont rapides.

Étape 1 — Déployer le serveur

SubSovereign est self-hosted, donc la première étape consiste à exécuter le backend sur votre propre infrastructure. Il s’agit d’un service Node.js/TypeScript alimenté par PostgreSQL (pour les droits d’accès, les événements et le consentement) et Redis (pour un cache rapide des droits d’accès).

cd backend
cp .env.example .env
# Fill in every value in .env — database URL, store credentials, secrets.

npm install
npm run migrate      # creates the database tables
npm run build && npm start

Pour un déploiement managé, une configuration Northflank prête à l’emploi est disponible (backend/northflank.yml), mais tout hébergeur exécutant Node + PostgreSQL + Redis convient — l’essentiel est que ce soit le vôtre. Une fois le serveur opérationnel, notez son adresse : c’est le baseUrl que vos applications utiliseront (par exemple https://subs.votredomaine.com).

Astuce : hébergez le serveur au Royaume-Uni ou dans l’UE. La souveraineté et le RGPD sont au cœur de notre proposition — ne renoncez pas à cet avantage dès l’étape de déploiement.

Étape 2 — Créer votre application dans le tableau de bord

Ouvrez le tableau de bord et créez une application — une par produit que vous publiez (vos applications Android et iOS peuvent correspondre au même enregistrement ou être séparées ; à vous de décider). La création d’une application vous fournit deux éléments essentiels :

  • un appId — identifie cette application auprès du serveur ;
  • une clé API — l’identifiant utilisé par votre application pour authentifier les appels SDK.

🚩 Copiez la clé API dès qu’elle apparaît et conservez-la dans un endroit sûr. Elle n’est affichée qu’une seule fois. Nous ne conservons qu’un hachage de celle-ci, elle ne pourra donc plus jamais être réaffichée. En cas de perte ou de fuite, vous n’aurez pas besoin de créer une nouvelle application : ouvrez l’application dans le tableau de bord, puis sous SDK keys appuyez sur New key pour en générer une autre, ou sur Revoke pour désactiver l’ancienne. La révocation est immédiate et irréversible — tout service utilisant encore cette clé cesse de nous atteindre dès que vous confirmez l’opération.

Étape 3 — Définir vos offres

Toujours dans le tableau de bord, configurez les éléments que vos utilisateurs achèteront :

  1. Créez vos niveaux d’accès (ou paliers) — les niveaux d’accès que votre produit propose, comme pro ou premium. Ce sont les noms que votre application utilisera pour vérifier les droits.
  2. Associez chaque niveau d’accès à vos produits en magasin. Dans chaque magasin (Apple, Google, Amazon, Roku, Stripe), créez les produits d’abonnement comme d’habitude ; dans SubSovereign, indiquez-lui « ce produit en magasin accorde ce niveau d’accès ». Cette correspondance transforme un achat en droit d’accès.
  3. Concevez votre paywall — titres, fonctionnalités, prix et durées d’essai. Comme cette interface est servie à distance, vous pouvez la modifier ultérieurement sans publier de mise à jour de l’application.

Si vous vendez via Stripe

La configuration de votre fournisseur de paiement vous incombe. Suivez la documentation d’installation de Stripe, ajoutez notre adresse de webhook ainsi que les événements listés ci-dessous dans votre tableau de bord Stripe, enregistrez votre clé secrète Stripe sur la page de votre application, puis vérifiez que tout fonctionne avec un achat test avant de passer en production. SubSovereign agit en fonction des informations transmises par Stripe.

  1. Dans votre tableau de bord Stripe, ajoutez un endpoint de webhook à l’adresse <your SubSovereign server>/api/v1/webhooks/stripe?appId=<your app id>, en envoyant les événements suivants : customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, customer.subscription.paused, customer.subscription.resumed, invoice.paid, invoice.payment_failed. Stripe affichera alors le secret de signature du webhook (whsec_…) de l’endpoint.
  2. Sur la page de votre application (Applications → votre application → Identifiants du store), enregistrez votre clé secrète Stripe ainsi que ce secret de signature du webhook. Sans ce secret de signature, chaque message Stripe sera refusé.
  3. Une fois votre application connectée (Étape 4), testez-la en mode test de Stripe : un achat test doit activer l’accès du client, et son annulation immédiate dans le tableau de bord Stripe doit le désactiver. Une annulation en fin de période maintient l’accès jusqu’à la date de fin — cela est normal, ce n’est pas un dysfonctionnement.

Si la page de votre application affiche "Impossible de joindre Stripe pour cette application", cela signifie que la clé secrète enregistrée y est refusée par Stripe ou qu’aucune n’y est enregistrée. Dans l’attente de la résolution de ce problème, les annulations et les paiements échoués ne modifient pas l’accès de vos clients.

Étape 4 — Intégrer le SDK à votre application

Ajoutez le SDK à votre application et pointez-le vers votre serveur. La structure est identique sur toutes les plateformes — suivez le guide correspondant à la vôtre :

Chaque intégration configure le SDK une fois avec votre clé API, votre appId, l’adresse de base de votre serveur et un userId stable pour l’utilisateur connecté (utilisez le même identifiant partout pour que les droits suivent l’utilisateur sur tous ses appareils).

Étape 5 — Vérifier les droits et lancer

Une fois le SDK configuré, votre application effectue deux actions :

  • Au lancement, demandez les droits de l’utilisateur et débloquez les fonctionnalités en conséquence (le guide Android montre cela sous la forme checkEntitlements() ; chaque SDK dispose d’une méthode équivalente).
  • Après un achat, transmettez le reçu à SubSovereign pour que le serveur valide l’achat auprès du magasin et accorde le niveau d’accès — puis relancez la vérification et débloquez les fonctionnalités.

Votre intégration est opérationnelle. Avant de publier, vérifiez cette liste :

  • Serveur déployé sur un hébergement au Royaume-Uni ou dans l’UE, migration exécutée, accessible depuis votre application.
  • Application créée ; clé API conservée en lieu sûr ; l’application pointe vers votre adresse de base.
  • Niveaux d’accès définis et associés à de vrais produits en magasin dans tous les magasins que vous supportez.
  • Facturation des magasins (Google Play, StoreKit, Amazon, Roku, Stripe) fonctionnelle dans votre application.
  • Stripe : endpoint de webhook ajouté avec les événements ci-dessus, clé secrète et secret de signature du webhook enregistrés, un achat test ayant activé l’accès et une annulation immédiate l’ayant désactivé.
  • Vérification des droits au lancement ; validation du reçu après achat ; les deux testés sur un appareil réel avec un achat (bac à sable) réel.
  • Consentement RGPD enregistré là où vous le collectez.

Pour aller plus loin

Also in:EnglishDeutschEspañolFrançaisहिन्दीItaliano한국어NederlandsPolskiPortuguês