SubSovereign localizzazione — guida all’integrazione per Roku

Questa guida porta il tuo canale Roku da “non so chi mi ha pagato” a “il mio canale sblocca le funzionalità giuste per l’utente giusto, verificato sul mio server”. L’SDK è un singolo file BrightScript e non richiede esperienza pregressa con strumenti per abbonamenti.

Cosa fa SubSovereign per te

I tuoi utenti si abbonano tramite Roku Pay (Roku Channel Store). SubSovereign risponde in modo affidabile a una domanda per il tuo canale: cosa ha effettivamente pagato questo utente?

• Il canale chiede a SubSovereign l’entitlement dell’utente — l’accesso che ha sbloccato.
• La convalida della ricevuta avviene lato server, direttamente con Roku, quindi un client manomesso non può falsificare un abbonamento.
• È self-hosted: gira sulla tua infrastruttura, i dati dei tuoi utenti rimangono con te e non c’è alcuna percentuale sul fatturato — ti tieni il 100% di ciò che pagano gli utenti.

Non fidarti mai del dispositivo. Il dispositivo chiede; il server decide.

Prima di iniziare

Ti serviranno un server SubSovereign in esecuzione, un’app registrata nel dashboard (che ti fornirà un appId e una chiave API), e i tuoi livelli di accesso (tiers, ad esempio pro) creati e collegati ai tuoi prodotti Roku Pay. Configura i prodotti nel Roku Developer Dashboard e gestisci l’acquisto con roChannelStore come al solito — SubSovereign verificherà e registrerà l’acquisto in seguito.

Passo 1 — Aggiungi l’SDK

Inserisci SubSovereign.brs nella cartella source/ del tuo canale. Punto. Nessun gestore di pacchetti. Le chiamate HTTP usano roUrlTransfer con il bundle di certificati Roku già configurato.

Passo 2 — Configura una volta, all’avvio del canale

Chiama SubSovereign_Configure presto (ad esempio nel tuo Main), passando la chiave API, l’ID dell’app, un identificatore utente stabile e l’URL del tuo server:

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

Usa lo stesso userId ogni volta per un dato utente, in modo che il suo accesso lo segua tra dispositivi diversi. (La configurazione risiede su m, quindi configura nello stesso thread da cui chiamerai — vedi la nota nel Passo 6.)

Passo 3 — Verifica cosa può fare l’utente

SubSovereign_CheckEntitlements() restituisce un oggetto. Leggi hasAccess per una risposta rapida sì/no:

result = SubSovereign_CheckEntitlements()
if result.hasAccess = true
    unlockProFeatures()
else
    showFreeExperience()   ' livello gratuito, oppure invia l’utente allo Store del canale
end if

Se la richiesta fallisce, l’oggetto restituisce hasAccess = false e un campo error — quindi un problema di rete chiude l’accesso (bloccato), senza sbloccarlo accidentalmente.

Passo 4 — Vendi un abbonamento

Esegui l’acquisto tramite Roku Pay (roChannelStore) come al solito. Quando Roku restituisce una transazione andata a buon fine, passa il suo transactionId (con l’ID del prodotto e il livello di accesso che concede) a SubSovereign, in modo che il server lo convalidi direttamente con Roku:

result = SubSovereign_ValidateRokuPurchase(transactionId, productId, "pro")
if result.granted = true
    entitlements = SubSovereign_CheckEntitlements()   ' ricontrolla, poi sblocca
    unlockProFeatures()
end if

L’acquisto è reale solo dopo che il server lo ha confermato con Roku.

Passo 5 — Feature flag e consenso

Distribuisci funzionalità dal server senza aggiornare il canale:

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

Cattura il consenso GDPR (fire-and-forget):

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

Passo 6 — Esegui le chiamate di rete fuori dal thread di rendering

SubSovereign_CheckEntitlements e SubSovereign_ValidateRokuPurchase aspettano la risposta dal server (fino a 15 secondi). Non chiamarli mai nel thread di rendering/UI — una rete lenta bloccherebbe lo schermo. Eseguili all’interno di un nodo Task e passa il risultato alla tua scena:

' in una funzione del nodo Task:
SubSovereign_Configure(m.top.apiKey, m.top.appId, m.top.userId, m.top.baseUrl)
m.top.result = SubSovereign_CheckEntitlements()   ' campo osservato al quale la scena è in ascolto

La chiamata fire-and-forget SubSovereign_RecordConsent non attende risposta ed è sicura da chiamare direttamente.

Best practice

• Controlla all’avvio del canale in modo che l’accesso sia verificato appena l’utente raggiunge i contenuti protetti.
• Ricontrolla dopo un acquisto in modo che l’interfaccia rifletta immediatamente il nuovo accesso.
• Non fidarti mai del client — chiedi al server; è lui che ha verificato la transazione con Roku.
• Usa sempre un nodo Task per le chiamate di verifica degli entitlement e delle validazioni.

Riferimento rapido

Passi successivi

• Altre piattaforme hanno le loro guide: Android, iOS, Web / React Native.
• Nuovo ai concetti? Leggi Come funziona SubSovereign.