SubSovereign en Roku — guía de integración

Esta guía lleva tu canal de Roku desde "no tengo ni idea de quién me ha pagado" a "mi canal desbloquea las funciones correctas para el usuario correcto, verificado en mi propio servidor". El SDK es un único archivo BrightScript y no requiere experiencia previa con herramientas de suscripciones.

Qué hace SubSovereign por ti

Tus usuarios se suscriben a través de Roku Pay (la Tienda de Canales de Roku). SubSovereign responde una única pregunta para tu canal, de forma fiable: ¿qué ha pagado realmente este usuario?

• Tu canal consulta a SubSovereign por el derecho de acceso — lo que el usuario ha desbloqueado.
• La validación de recibo se realiza en el servidor, directamente con Roku, por lo que un cliente manipulado no puede falsificar una suscripción.
• Es autohospedado: se ejecuta en tu infraestructura, los datos de tus usuarios se quedan contigo y no hay reparto de ingresos — te quedas el 100% de lo que pagan tus usuarios.

Nunca confíes en el dispositivo. El dispositivo pregunta; el servidor decide.

Antes de empezar

Necesitarás un servidor de SubSovereign en ejecución, una app registrada en el panel de control (que te proporcionará un appId y una clave de API), y tus niveles de acceso (rangos, por ejemplo pro) creados y vinculados a tus productos de Roku Pay. Configura los productos en el Roku Developer Dashboard y gestiona la compra con roChannelStore como de costumbre — SubSovereign verifica y registra la compra después.

Paso 1 — Añadir el SDK

Coloca SubSovereign.brs en la carpeta source/ de tu canal. Eso es todo — sin gestor de paquetes. Sus llamadas HTTP usan roUrlTransfer con el paquete de certificados de Roku ya configurado.

Paso 2 — Configurar una vez, al iniciar el canal

Llama a SubSovereign_Configure al principio (por ejemplo, en tu Main), pasando tu clave de API, el ID de la app, un identificador de usuario estable y la URL de tu servidor:

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

Usa el mismo userId cada vez para un usuario determinado para que su acceso lo siga en todos los dispositivos. (La configuración reside en m, así que configúrala en el mismo hilo desde el que harás las llamadas — consulta la nota en el Paso 6.)

Paso 3 — Comprobar qué puede acceder el usuario

SubSovereign_CheckEntitlements() devuelve un objeto. Lee hasAccess para la respuesta rápida sí/no:

result = SubSovereign_CheckEntitlements()
if result.hasAccess = true
    unlockProFeatures()
else
    showFreeExperience()   ' rango gratuito, o envíalos a la Tienda de Canales
end if

Si la petición falla, el objeto devuelve hasAccess = false y un campo error — por lo que un fallo de red cierra el acceso (bloqueado), nunca se desbloquea accidentalmente.

Paso 4 — Vender una suscripción

Realiza la compra a través de Roku Pay (roChannelStore) como de costumbre. Cuando Roku devuelva una transacción exitosa, pasa su transactionId (junto con el ID del producto y el nivel de acceso que concede) a SubSovereign para que el servidor lo valide directamente con Roku:

result = SubSovereign_ValidateRokuPurchase(transactionId, productId, "pro")
if result.granted = true
    entitlements = SubSovereign_CheckEntitlements()   ' vuelve a comprobar, luego desbloquea
    unlockProFeatures()
end if

La compra solo es real una vez que el servidor la ha confirmado con Roku.

Paso 5 — Bandera de funciones y consentimiento

Lanza funciones desde el servidor sin actualizar el canal:

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

Captura el consentimiento GDPR (dispara y olvida):

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

Paso 6 — Ejecutar llamadas de red fuera del hilo de renderizado

SubSovereign_CheckEntitlements y SubSovereign_ValidateRokuPurchase esperan al servidor (hasta 15 segundos). Nunca las llames en el hilo de renderizado/UI — una red lenta congelaría la pantalla. Ejecútalas dentro de un nodo Task y pasa el resultado de vuelta a tu escena:

' en una función de un nodo Task:
SubSovereign_Configure(m.top.apiKey, m.top.appId, m.top.userId, m.top.baseUrl)
m.top.result = SubSovereign_CheckEntitlements()   ' campo observado que la escena escucha

La llamada de disparar y olvidar SubSovereign_RecordConsent no espera respuesta y es seguro llamarla directamente.

Buenas prácticas

• Comprobar al iniciar el canal para que el acceso esté correcto antes de que el usuario llegue al contenido bloqueado.
• Revisar después de comprar para que la interfaz refleje el nuevo acceso al instante.
• Nunca confíes en el cliente — pregunta al servidor; es el que verificó la transacción con Roku.
• Usa siempre un nodo Task para las llamadas de acceso y validación.

Referencia rápida

Pasos siguientes

• Otras plataformas tienen sus propias guías: Android, iOS, Web / React Native.
• ¿Nuevo en estos conceptos? Lee Cómo funciona SubSovereign.