SubSovereign auf Roku — Integrationsanleitung

Diese Anleitung führt Ihr Roku-Channel von „Ich habe keine Ahnung, wer mir etwas bezahlt hat“ zu „Mein Channel entsperrt die richtigen Funktionen für den richtigen Nutzer – verifiziert auf meinem eigenen Server.“ Das SDK besteht aus einer einzigen BrightScript-Datei und setzt keine Vorkenntnisse mit Abonnement-Tools voraus.

Was SubSovereign für Sie tut

Ihre Nutzer abonnieren über Roku Pay (den Roku Channel Store). SubSovereign beantwortet eine Frage für Ihren Channel zuverlässig: Wofür hat dieser Nutzer tatsächlich bezahlt?

• Ihr Channel fragt SubSovereign nach der Berechtigung des Nutzers – dem Zugang, den er durch einen Kauf oder ein Abo erhalten hat.
• Die serverseitige Überprüfung der Kaufbelege erfolgt direkt mit Roku, sodass ein manipuliertes Client-Gerät keine Abos vortäuschen kann.
• Es ist selbstgehostet: Es läuft auf Ihrer Infrastruktur, die Nutzerdaten bleiben bei Ihnen, und es gibt keine Gewinnbeteiligung – Sie behalten 100 % dessen, was Ihre Nutzer zahlen.

Sie vertrauen dem Gerät nie. Das Gerät fragt an; der Server entscheidet.

Vorbereitung

Sie benötigen einen laufenden SubSovereign-Server, eine im Dashboard registrierte App (die Ihnen eine appId und einen API-Schlüssel gibt) sowie Ihre Zugangsebenen (Tiers, z. B. pro), die mit Ihren Roku-Pay-Produkten verknüpft sind. Richten Sie die Produkte im Roku Developer Dashboard ein und behandeln Sie den Kauf wie gewohnt mit roChannelStore – SubSovereign überprüft und protokolliert ihn anschließend.

Schritt 1 — SDK hinzufügen

Legen Sie SubSovereign.brs in den Ordner source/ Ihres Channels. Das war’s – kein Paketmanager nötig. Die HTTP-Aufrufe nutzen roUrlTransfer mit dem bereits integrierten Roku-Zertifikatspaket.

Schritt 2 — Einmalige Konfiguration beim Start des Channels

Rufen Sie SubSovereign_Configure früh auf (z. B. in Main) und übergeben Sie Ihren API-Schlüssel, die App-ID, eine stabile Nutzerkennung sowie Ihre Server-URL:

SubSovereign_Configure("YOUR_APP_API_KEY", "your-app-id", userId, "https://subs.yourdomain.com/api/v1")

Verwenden Sie für einen bestimmten Nutzer immer dieselbe userId, damit sein Zugang geräteübergreifend erhalten bleibt. (Die Konfiguration wird in m gespeichert – konfigurieren Sie sie auf demselben Thread, von dem aus Sie später aufrufen – siehe Hinweis in Schritt 6.)

Schritt 3 — Prüfen, auf was der Nutzer zugreifen kann

SubSovereign_CheckEntitlements() gibt ein Objekt zurück. Lesen Sie hasAccess für die schnelle Ja/Nein-Antwort:

result = SubSovereign_CheckEntitlements()
if result.hasAccess = true
    unlockProFeatures()
else
    showFreeExperience()   ' kostenlose Stufe oder Weiterleitung zum Channel Store
end if

Falls der Aufruf fehlschlägt, enthält das Objekt hasAccess = false und ein error-Feld – ein Netzwerkproblem führt also zu einer geschlossenen Abfrage (gesperrt), nie zu einer versehentlichen Freigabe.

Schritt 4 — Abo verkaufen

Führen Sie den Kauf wie gewohnt über Roku Pay (roChannelStore) durch. Wenn Roku eine erfolgreiche Transaktion zurückgibt, übergeben Sie die transactionId (mit der Produkt-ID und der Zugangsebene, die sie gewährt) an SubSovereign, damit der Server sie direkt mit Roku überprüft:

result = SubSovereign_ValidateRokuPurchase(transactionId, productId, "pro")
if result.granted = true
    entitlements = SubSovereign_CheckEntitlements()   ' nochmal prüfen, dann freischalten
    unlockProFeatures()
end if

Der Kauf ist erst dann echt, wenn der Server ihn mit Roku bestätigt hat.

Schritt 5 — Feature-Flags und Einwilligung

Rollen Sie Funktionen serverseitig aus, ohne den Channel zu aktualisieren:

flags = SubSovereign_GetFeatureFlags()
if flags.newPlayer = true then showNewPlayer()

Erfassen Sie die GDPR-Einwilligung (Fire-and-Forget):

purposes = { analytics: true, marketing: false }
SubSovereign_RecordConsent(purposes, "GDPR")

Schritt 6 — Netzwerkanfragen außerhalb des Render-Threads ausführen

SubSovereign_CheckEntitlements und SubSovereign_ValidateRokuPurchase warten auf den Server (bis zu 15 Sekunden). Rufen Sie sie niemals auf Ihrem Render-/UI-Thread auf – ein langsames Netzwerk würde den Bildschirm einfrieren. Führen Sie sie in einem Task-Knoten aus und leiten Sie das Ergebnis an Ihre Szene weiter:

' in einer Funktion des Task-Knotens:
SubSovereign_Configure(m.top.apiKey, m.top.appId, m.top.userId, m.top.baseUrl)
m.top.result = SubSovereign_CheckEntitlements()   ' beobachtetes Feld, das die Szene abonniert

Der Fire-and-Forget-Aufruf SubSovereign_RecordConsent wartet nicht auf eine Antwort und kann direkt aufgerufen werden.

Best Practices

• Beim Start des Channels prüfen, damit die Sperre direkt vor dem Erreichen gesperrter Inhalte aktiv ist.
• Nach einem Kauf nochmal prüfen, damit die UI den neuen Zugang sofort widerspiegelt.
• Vertrauen Sie dem Client nie – fragen Sie den Server; dieser hat die Transaktion mit Roku überprüft.
• Verwenden Sie für Berechtigungs- und Validierungsaufrufe immer einen Task-Knoten.

Schnellreferenz

Nächste Schritte

• Andere Plattformen haben eigene Anleitungen: Android, iOS, Web / React Native.
• Neue Konzepte? Lesen Sie Wie SubSovereign funktioniert.