SubSovereign na Roku — guia de integração

Este guia leva o seu canal Roku de "não faço ideia de quem me pagou" a "o meu canal desbloqueia as funcionalidades certas para o utilizador certo, verificado no meu próprio servidor". O SDK é um único ficheiro BrightScript e não pressupõe experiência prévia com ferramentas de subscrição.

O que o SubSovereign faz por si

Os seus utilizadores subscrevem através do Roku Pay (a Loja de Canais Roku). O SubSovereign responde, de forma fiável, a uma única pergunta para o seu canal: o que é que este utilizador pagou, realmente?

• O seu canal pergunta ao SubSovereign pelo direito de acesso do utilizador — o que ele desbloqueou.
• A validação da recibo é feita no servidor, diretamente com a Roku, para que um cliente adulterado não consiga falsificar uma subscrição.
• É auto-hospedado: funciona na sua infraestrutura, os dados dos seus utilizadores ficam consigo e não há partilha de receitas — mantém 100% do que os seus utilizadores pagam.

Nunca confia no dispositivo. O dispositivo pergunta; o servidor decide.

Antes de começar

Precisa de um servidor SubSovereign em execução, de um aplicação registada no painel (que lhe fornece um appId e uma chave de API), e dos seus níveis de acesso (tier, por exemplo, pro) criados e associados aos seus produtos do Roku Pay. Configure os produtos no Roku Developer Dashboard e processe a compra com roChannelStore como habitualmente — o SubSovereign verifica e regista-a depois.

Passo 1 — Adicionar o SDK

Coloque o SubSovereign.brs na pasta source/ do seu canal. É só isso — sem gestor de pacotes. As chamadas HTTP usam roUrlTransfer com o pacote de certificados da Roku já configurado.

Passo 2 — Configurar uma vez, no início do canal

Chame SubSovereign_Configure cedo (por exemplo, no seu Main), passando a sua chave de API, ID da aplicação, um identificador de utilizador estável e a URL do seu servidor:

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

Use o mesmo userId todas as vezes para um dado utilizador, para que o respetivo acesso o siga entre dispositivos. (A configuração fica em m, por isso configure no mesmo thread de onde vai chamar — veja a nota no Passo 6.)

Passo 3 — Verificar o que o utilizador pode aceder

SubSovereign_CheckEntitlements() devolve um objeto. Leia hasAccess para uma resposta rápida sim/não:

result = SubSovereign_CheckEntitlements()
if result.hasAccess = true
    unlockProFeatures()
else
    showFreeExperience()   ' nível gratuito, ou envie-os para a Loja de Canais
end if

Se a pedido falhar, o objeto é devolvido com hasAccess = false e um campo error — por isso, um problema de rede falha no modo fechado (bloqueado), nunca acidentalmente desbloqueado.

Passo 4 — Vender uma subscrição

Processa a compra através do Roku Pay (roChannelStore) como habitualmente. Quando a Roku devolver uma transação bem-sucedida, passe o respetivo transactionId (com o ID do produto e o nível de acesso que concede) ao SubSovereign para que o servidor valide diretamente com a Roku:

result = SubSovereign_ValidateRokuPurchase(transactionId, productId, "pro")
if result.granted = true
    entitlements = SubSovereign_CheckEntitlements()   ' verifique novamente, depois desbloqueie
    unlockProFeatures()
end if

A compra só é real depois de o servidor a ter confirmado com a Roku.

Passo 5 — Feature flags e consentimento

Lance funcionalidades a partir do servidor sem atualizar o canal:

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

Capture o consentimento GDPR (fire-and-forget):

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

Passo 6 — Executar chamadas de rede fora do thread de renderização

SubSovereign_CheckEntitlements e SubSovereign_ValidateRokuPurchase esperam pelo servidor (até 15 segundos). Nunca os chame no seu thread de renderização/UI — uma rede lenta congelaria o ecrã. Execute-os dentro de um nó Task e passe o resultado de volta para a sua cena:

' numa função de um nó Task:
SubSovereign_Configure(m.top.apiKey, m.top.appId, m.top.userId, m.top.baseUrl)
m.top.result = SubSovereign_CheckEntitlements()   ' campo observado que a cena escuta

A chamada fire-and-forget SubSovereign_RecordConsent não espera por uma resposta e pode ser chamada diretamente com segurança.

Melhores práticas

• Verifique no lançamento do canal para que o bloqueio seja feito antes de o utilizador chegar ao conteúdo bloqueado.
• Verifique novamente após a compra para que a interface reflita imediatamente o novo acesso.
• Nunca confie no cliente — pergunte ao servidor; este verificou a transação com a Roku.
• Use sempre um nó Task para as chamadas de direitos e validação.

Referência rápida

Próximos passos

• Outras plataformas têm os seus próprios guias: Android, iOS, Web / React Native.
• Novo nestes conceitos? Leia Como funciona o SubSovereign.