SubSovereign sur Roku — guide d’intégration

Ce guide transforme votre chaîne Roku d’un simple "Je ne sais pas qui m’a payé" à un système où votre chaîne débloque les bonnes fonctionnalités pour le bon utilisateur, avec une vérification effectuée sur votre propre serveur. Le SDK se compose d’un seul fichier BrightScript et ne nécessite aucune expérience préalable avec les outils de gestion d’abonnements.

Ce que SubSovereign fait pour vous

Vos utilisateurs s’abonnent via Roku Pay (le Roku Channel Store). SubSovereign répond de manière fiable à une seule question pour votre chaîne : qu’a réellement payé cet utilisateur ?

• Votre chaîne interroge SubSovereign pour obtenir l’accès (l’accès qu’il a débloqué) de l’utilisateur.
• La validation côté serveur s’effectue sur le serveur, directement avec Roku, ce qui empêche un client falsifié de simuler un abonnement.
• Il s’agit d’une solution auto-hébergée : elle s’exécute sur votre infrastructure, les données de vos utilisateurs restent chez vous, et il n’y a aucune part de revenus — vous conservez 100 % de ce que paient vos utilisateurs.

Vous ne faites jamais confiance à l’appareil. L’appareil pose la question ; le serveur prend la décision.

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 (paliers, par exemple pro) créés et liés à vos produits Roku Pay. Configurez les produits dans le Roku Developer Dashboard et gérez l’achat avec roChannelStore comme d’habitude — SubSovereign vérifie et enregistre l’achat ensuite.

Étape 1 — Ajouter le SDK

Placez SubSovereign.brs dans le dossier source/ de votre chaîne. C’est tout — aucun gestionnaire de paquets requis. Ses appels HTTP utilisent roUrlTransfer avec le bundle de certificats Roku déjà configuré.

Étape 2 — Configurer une seule fois, au démarrage de la chaîne

Appelez SubSovereign_Configure tôt (par exemple dans votre Main), en transmettant votre clé API, l’ID de l’application, un identifiant utilisateur stable, et l’URL de votre serveur :

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

Utilisez le même userId à chaque fois pour un utilisateur donné afin que son accès le suive sur tous les appareils. (La configuration est stockée dans m, configurez donc sur le même thread depuis lequel vous effectuerez les appels — voir la note à l’étape 6.)

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

SubSovereign_CheckEntitlements() renvoie un objet. Consultez hasAccess pour une réponse rapide oui/non :

result = SubSovereign_CheckEntitlements()
if result.hasAccess = true
    unlockProFeatures()
else
    showFreeExperience()   ' palier gratuit, ou envoyez-les vers le Roku Channel Store
end if

Si la requête échoue, l’objet revient avec hasAccess = false et un champ error — ainsi, une coupure réseau entraîne un échec en mode verrouillé (fermé), jamais un déverrouillage accidentel.

Étape 4 — Vendre un abonnement

Effectuez l’achat via Roku Pay (roChannelStore) comme d’habitude. Lorsque Roku renvoie une transaction réussie, transmettez son transactionId (avec l’ID du produit et le niveau d’accès qu’il accorde) à SubSovereign afin que le serveur le valide directement avec Roku :

result = SubSovereign_ValidateRokuPurchase(transactionId, productId, "pro")
if result.granted = true
    entitlements = SubSovereign_CheckEntitlements()   ' vérifiez à nouveau, puis déverrouillez
    unlockProFeatures()
end if

L’achat n’est réel que lorsque le serveur l’a confirmé avec Roku.

Étape 5 — Drapeaux de fonctionnalités et consentement

Déployez des fonctionnalités depuis le serveur sans mettre à jour la chaîne :

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

Capturez le consentement RGPD (sans attente de réponse) :

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

Étape 6 — Exécuter les appels réseau hors du thread de rendu

SubSovereign_CheckEntitlements et SubSovereign_ValidateRokuPurchase attendent la réponse du serveur (jusqu’à 15 secondes). Ne les appelez jamais sur le thread de rendu/UI de votre chaîne — un réseau lent figera l’écran. Exécutez-les dans un nœud Task et transmettez le résultat à votre scène :

' dans une fonction du nœud Task :
SubSovereign_Configure(m.top.apiKey, m.top.appId, m.top.userId, m.top.baseUrl)
m.top.result = SubSovereign_CheckEntitlements()   ' champ observé que la scène écoute

L’appel sans attente SubSovereign_RecordConsent ne nécessite pas de réponse et peut être appelé directement en toute sécurité.

Bonnes pratiques

• Vérifiez au lancement de la chaîne pour que le contrôle d’accès intervienne juste avant que l’utilisateur n’accède au contenu verrouillé.
• Vérifiez à nouveau après un achat pour que l’interface reflète immédiatement le nouvel accès.
• Ne faites jamais confiance au client — interrogez le serveur ; c’est lui qui a vérifié la transaction avec Roku.
• Utilisez toujours un nœud Task pour les appels d’accès et de validation.

Référence rapide

Prochaines étapes

• D’autres plateformes ont leurs propres guides : Android, iOS, Web / React Native.
• Nouveau sur ces concepts ? Lisez Comment fonctionne SubSovereign.