SubSovereign
← All guides

Aan de slag met SubSovereign

Deze gids neemt je mee van nul naar een werkende abonnementscontrole in je app. Het is de praktische aanvulling op Hoe SubSovereign werkt — lees die eerst als je de concepten wilt begrijpen.

Er zijn vijf stappen: server opzetten → app maken → verkopen definiëren → SDK toevoegen → toegang controleren. Budget een middag voor de eerste stap; de rest gaat snel.

Stap 1 — Server opzetten

SubSovereign is zelf gehost, dus de eerste stap is het draaien van de backend op je eigen infrastructuur. Het is een Node.js/TypeScript-service met als backend PostgreSQL (voor toegangsrechten, gebeurtenissen en toestemming) en Redis (voor een snelle cache van toegangsrechten).

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

Voor een beheerde implementatie is er een kant-en-klaar Northflank-configuratiebestand (backend/northflank.yml), maar elke host die Node + PostgreSQL + Redis draait werkt — het gaat erom dat jij het beheert. Zodra de server draait, noteer je het adres; dat is de baseUrl waar je apps mee communiceren (bijv. https://subs.jouwdomein.nl).

Tip: houd de server op UK/EU-hosting. Soevereiniteit en GDPR zijn het hele punt — geef dat niet weg bij de implementatiestap.

Stap 2 — App maken in het dashboard

Open het dashboard en maak een app aan — één per product dat je uitbrengt (je Android-app en iOS-app kunnen hetzelfde app-record zijn of apart; dat bepaal je zelf). Het maken van een app geeft je twee dingen die je nodig hebt:

  • een appId — identificeert deze app voor de server, en
  • een API-sleutel — de referentie die je app gebruikt om de SDK-aanroepen te authenticeren.

🚩 Kopieer de API key op het moment dat deze verschijnt en sla deze veilig op. Deze wordt maar één keer getoond. Wij slaan alleen een hash van de key op, dus deze kan nooit meer worden weergegeven. Mocht u deze verliezen of als deze uitlekt, dan hoeft u geen nieuwe app aan te maken: open de app in het dashboard, ga onder SDK keys naar New key om een nieuwe aan te maken of naar Revoke om de oude te deactiveren. Deactiveren gebeurt direct en kan niet ongedaan worden gemaakt — alles wat nog gebruikmaakt van die key, stopt met communiceren zodra u de actie bevestigt.

Stap 3 — Definieer wat je verkoopt

Blijf in het dashboard en stel de zaken in die je gebruikers daadwerkelijk gaan kopen:

  1. Maak je toegangsniveaus (ook wel tiers genoemd) — de niveaus van toegang die je product biedt, zoals pro of premium. Dit zijn de namen die je app zal controleren.
  2. Koppel elk toegangsniveau aan je winkelproducten. Maak in elke winkel (App Store, Google Play, Amazon, Roku, Stripe) de abonnementsproducten zoals normaal; in SubSovereign geef je aan "dit winkelproduct geeft dit toegangsniveau." Die koppeling zorgt ervoor dat een aankoop een toegangsrecht wordt.
  3. Ontwerp je betaalmuur — de kop, functies, prijzen en proefperiode. Omdat dit op afstand wordt geleverd, kun je dit later wijzigen zonder een app-update uit te brengen.

Als je via Stripe verkoopt

Het instellen van je betaalprovider is jouw verantwoordelijkheid. Volg Stripe’s eigen installatiehandleiding, voeg ons webhookadres toe en de onderstaande events in je Stripe-dashboard, bewaar je Stripe geheime sleutel op de pagina van je app en controleer of alles werkt met een testaankoop voordat je live gaat. SubSovereign handelt op basis van wat Stripe ons meldt.

  1. Voeg in je Stripe-dashboard een webhook-eindpunt toe op <your SubSovereign server>/api/v1/webhooks/stripe?appId=<your app id>, met deze events: customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, customer.subscription.paused, customer.subscription.resumed, invoice.paid, invoice.payment_failed. Stripe toont dan het Stripe webhook-ondertekeningsgeheim (whsec_…) van het eindpunt.
  2. Bewaar op de pagina van je app (Apps → jouw app → Winkelgegevens) je Stripe geheime sleutel en dat Stripe webhook-ondertekeningsgeheim. Zonder het ondertekeningsgeheim wordt elk Stripe-bericht geweigerd.
  3. Zodra je app verbonden is (Stap 4), test je in Stripe’s testmodus: een testaankoop moet de toegang van de klant inschakelen, en deze direct annuleren in Stripe’s dashboard moet de toegang uitschakelen. Een annulering aan het eind van de periode houdt de toegang aan tot de einddatum — dat is correct, geen fout.

Als op de pagina van je app "We kunnen Stripe niet bereiken voor deze app" staat, heeft Stripe de opgeslagen geheime sleutel geweigerd of is er geen opgeslagen — totdat dat is opgelost, wijzigen annuleringen en mislukte betalingen de toegang van je klanten niet.

Stap 4 — SDK toevoegen aan je app

Voeg de SDK toe aan je app en richt deze op je server. De opzet is op elk platform identiek — volg de gids voor jouw platform:

Elke SDK wordt eenmalig geconfigureerd met je apiKey, appId, je server-baseUrl en een stabiele userId voor de ingelogde gebruiker (gebruik dezelfde ID overal, zodat toegang de gebruiker volgt op alle apparaten).

Stap 5 — Toegang controleren en live gaan

Met de SDK geconfigureerd doet je app twee dingen:

  • Bij het opstarten vragen wat de gebruiker heeft en dienovereenkomstig ontgrendelen (de Android-gids toont dit als checkEntitlements(); elke SDK heeft de equivalente functie).
  • Na een aankoop de ontvangstbewijs doorgeven aan SubSovereign zodat de server dit valideert met de winkel en het bijbehorende toegangsniveau verstrekt — controleer daarna opnieuw en ontgrendel.

Dat is een werkende integratie. Voordat je uitbrengt, een korte checklist:

  • Server geïmplementeerd op UK/EU-hosting, migratie uitgevoerd, bereikbaar vanuit je app.
  • App gemaakt; API-sleutel veilig opgeslagen; de app richt zich op je baseUrl.
  • Toegangsniveaus gedefinieerd en gekoppeld aan echte winkelproducten in elke winkel die je ondersteunt.
  • Winkelbilling (Google Play / StoreKit / Amazon / Roku / Stripe) werkt in je app.
  • Stripe: webhook-eindpunt toegevoegd met de bovenstaande events, geheime sleutel en webhook-ondertekeningsgeheim opgeslagen, een testaankoop gezien die toegang inschakelt en een directe annulering gezien die toegang uitschakelt.
  • Toegangscontrole bij opstarten; ontvangstbewijsvalidatie na aankoop; beide getest op een echt apparaat met een echte (sandbox) aankoop.
  • GDPR-toestemming geregistreerd waar je deze verzamelt.

Waar ga je heen vanaf hier

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