SubSovereign
← All guides

Erste Schritte mit SubSovereign

Dieser Leitfaden führt dich von Grund auf zu einer funktionierenden Abonnement-Prüfung in deiner App. Er ist der praktische Begleiter zu Wie SubSovereign funktioniert – lies diesen zuerst, wenn du die Konzepte verstehen möchtest.

Es gibt fünf Schritte: Server einrichten → App erstellen → Verkaufsangebot definieren → SDK hinzufügen → Zugriff prüfen. Plane für den ersten Schritt einen Nachmittag ein; die restlichen gehen schnell.

Schritt 1 — Server einrichten

SubSovereign ist selbstgehostet, daher beginnt alles damit, den Backend-Dienst auf deiner eigenen Infrastruktur auszuführen. Es handelt sich um einen Node.js/TypeScript-Dienst, der von PostgreSQL (für Berechtigungen, Ereignisse und Einwilligungen) und Redis (für einen schnellen Berechtigungscache) unterstützt wird.

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

Für eine verwaltete Bereitstellung gibt es eine fertige Northflank-Konfiguration (backend/northflank.yml), aber jeder Host, der Node + PostgreSQL + Redis ausführt, funktioniert – entscheidend ist, dass er dir gehört. Sobald der Server läuft, notiere dir seine Adresse; dies ist die baseUrl, mit der sich deine Apps verbinden (z. B. https://subs.deinedomain.com).

Tipp: Halte den Server auf UK-/EU-Hosting. Souveränität und GDPR sind der ganze Sinn – gib das nicht beim Deployment auf.

Schritt 2 — App im Dashboard erstellen

Öffne das Dashboard und erstelle eine App – eine pro Produkt, das du veröffentlichst (deine Android- und iOS-App können dieselbe App sein oder separat; liegt bei dir). Beim Erstellen der App erhältst du zwei Dinge, die du benötigst:

  • eine appId – identifiziert diese App gegenüber dem Server und
  • einen API-Schlüssel – das Anmeldeinformation, mit dem deine App die SDK-Aufrufe authentifiziert.

🚩 Kopieren Sie den API-Schlüssel in dem Moment, in dem er angezeigt wird, und speichern Sie ihn an einem sicheren Ort ab. Er wird nur einmal angezeigt. Wir speichern lediglich einen Hash davon, sodass er niemals erneut angezeigt werden kann. Sollten Sie ihn verlieren oder er sollte in falsche Hände geraten, müssen Sie keine neue App erstellen: Öffnen Sie die App im Dashboard, und wählen Sie unter SDK keys die Option New key, um einen neuen Schlüssel zu generieren, oder Revoke, um den alten zu deaktivieren. Die Deaktivierung erfolgt umgehend und kann nicht rückgängig gemacht werden — alles, was diesen Schlüssel noch verwendet, kann uns ab dem Moment der Bestätigung nicht mehr erreichen.

Schritt 3 — Verkaufsangebot definieren

Bleibe im Dashboard und richte die Dinge ein, die deine Nutzer:innen tatsächlich kaufen werden:

  1. Zugriffsebenen (auch „Stufen“ genannt) erstellen – die Ebenen, die dein Produkt gewährt, z. B. pro oder premium. Dies sind die Namen, gegen die deine App prüft.
  2. Jede Zugriffsebene mit deinen Store-Produkten verknüpfen. In jedem Store (App Store, Google Play, Amazon, Roku, Stripe) erstellst du die Abo-Produkte wie gewohnt; in SubSovereign teilst du ihm mit: „Dieses Store-Produkt gewährt diese Zugriffsebene.“ Diese Zuordnung wandelt einen Kauf in eine Berechtigung um.
  3. Paywall gestalten – Überschrift, Funktionen, Preise und Testdauern. Da diese remote ausgeliefert wird, kannst du sie später ändern, ohne ein App-Update zu veröffentlichen.

Wenn du über Stripe verkaufst

Die Einrichtung deines Zahlungsanbieters liegt in deiner Verantwortung. Folge Stripes eigener Installationsdokumentation, füge unsere Webhook-Adresse und die unten aufgelisteten Events in deinem Stripe-Dashboard hinzu, speichere deinen Stripe-Geheimschlüssel auf der Seite deiner App und prüfe, dass alles mit einem Testkauf funktioniert, bevor du live gehst. SubSovereign handelt entsprechend den Informationen, die Stripe uns übermittelt.

  1. Füge in deinem Stripe-Dashboard einen Webhook-Endpoint unter <your SubSovereign server>/api/v1/webhooks/stripe?appId=<your app id> hinzu und sende diese Events: customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, customer.subscription.paused, customer.subscription.resumed, invoice.paid, invoice.payment_failed. Stripe zeigt dir dann das Webhook-Signatur-Geheimnis (whsec_…) dieses Endpoints an.
  2. Speichere auf der Seite deiner App (Apps → deine App → Store-Anmeldedaten) deinen Stripe-Geheimschlüssel und dieses Webhook-Signatur-Geheimnis. Ohne das Signatur-Geheimnis wird jede Stripe-Nachricht abgelehnt.
  3. Sobald deine App verbunden ist (Schritt 4), teste sie im Testmodus von Stripe: Ein Testkauf sollte den Zugang des Kunden freischalten, und ein sofortiges Kündigen im Stripe-Dashboard sollte ihn sperren. Eine Kündigung am Ende der Periode behält den Zugang bis zum Enddatum – das ist korrekt, kein Fehler.

Falls auf der Seite deiner App "Stripe kann für diese App nicht erreicht werden" angezeigt wird, hat Stripe den gespeicherten Geheimschlüssel abgelehnt oder es ist keiner gespeichert – solange das nicht behoben ist, ändern Kündigungen und fehlgeschlagene Zahlungen den Zugang deiner Kunden nicht.

Schritt 4 — SDK zur App hinzufügen

Füge das SDK zu deiner App hinzu und richte es auf deinen Server aus. Die Struktur ist auf jeder Plattform identisch – folge dem Leitfaden für deine:

Jede Anleitung konfiguriert das SDK einmal mit deinem apiKey, appId, deiner Server-baseUrl und einer stabilen userId für die angemeldete Nutzer:in (verwende dieselbe ID überall, damit der Zugriff den Nutzer:innen über Geräte hinweg folgt).

Schritt 5 — Zugriff prüfen und live schalten

Sobald das SDK konfiguriert ist, erledigt deine App zwei Dinge:

  • Beim Start abfragen, was die Nutzer:in hat, und entsprechend freischalten (der Android-Leitfaden zeigt dies als checkEntitlements(); jedes SDK hat das entsprechende Äquivalent).
  • Nach einem Kauf die Quittung an SubSovereign übergeben, damit der Server sie mit dem Store validiert und die Zugriffsebene gewährt – dann erneut prüfen und freischalten.

Damit ist die Integration abgeschlossen. Vor dem Veröffentlichen eine kurze Checkliste:

  • Server auf UK-/EU-Hosting bereitgestellt, Migration ausgeführt, von deiner App erreichbar.
  • App erstellt; API-Schlüssel sicher gespeichert; die App zeigt auf deine baseUrl.
  • Zugriffsebenen definiert und mit echten Store-Produkten in jedem Store verknüpft, den du unterstützt.
  • Store-Abrechnung (Google Play / StoreKit / Amazon / Roku / Stripe) in deiner App funktionsfähig.
  • Stripe: Webhook-Endpoint mit den oben genannten Events hinzugefügt, Geheimschlüssel und Webhook-Signatur-Geheimnis gespeichert, ein Testkauf hat den Zugang freigeschaltet und eine sofortige Kündigung hat ihn gesperrt.
  • Berechtigungsprüfung beim Start; Quittungsvalidierung nach Kauf; beide auf einem echten Gerät mit einem echten (Sandbox-)Kauf getestet.
  • GDPR-Einwilligung erfasst, wo du sie erhebst.

Nächste Schritte

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