SubSovereign
← All guides

Começar com o SubSovereign

Este guia leva-o desde o início até uma verificação funcional de subscrição na sua aplicação. É o companheiro prático de Como funciona o SubSovereign — leia-o primeiro se quiser perceber os conceitos.

Existem cinco etapas: implementar o servidor → criar a sua aplicação → definir o que vende → adicionar o SDK → verificar o acesso. Reserve uma tarde para a primeira; as restantes são rápidas.

Etapa 1 — Implementar o servidor

O SubSovereign é self-hosted, por isso a primeira etapa é executar o backend na sua própria infraestrutura. Trata-se de um serviço Node.js/TypeScript suportado por PostgreSQL (para direitos de acesso, eventos e consentimento) e Redis (para uma cache rápida de direitos de acesso).

cd backend
cp .env.example .env
# Fill in every value in .env — database URL, store credentials, secrets.

npm install
npm run migrate      # creates the database tables
npm run build && npm start

Para uma implementação gerida, existe uma configuração pronta a usar para o Northflank (backend/northflank.yml), mas qualquer servidor que execute Node + PostgreSQL + Redis funciona — o ponto é que é seu. Quando estiver pronto, anote o seu endereço; é o baseUrl com o qual as suas aplicações irão comunicar (por exemplo, https://subs.yourdomain.com).

Dica: mantenha o servidor num alojamento no Reino Unido/UE. A soberania e o RGPD são o cerne da questão — não abdique disso na fase de implementação.

Etapa 2 — Criar a sua aplicação no painel de controlo

Abra o painel de controlo e crie uma aplicação — uma por produto que distribuir (a sua aplicação Android e iOS podem ser o mesmo registo de aplicação ou separados; depende de si). Criar uma aplicação dá-lhe duas coisas de que precisará:

  • um appId — identifica esta aplicação no servidor, e
  • uma chave de API — a credencial que a sua aplicação utiliza para autenticar as chamadas ao SDK.

🚩 Copie a chave da API no momento em que ela aparece e guarde-a num local seguro. Ela é mostrada apenas uma vez. Apenas mantemos um hash dela, pelo que não poderá ser apresentada novamente. Se a perder ou se for exposta, não precisa de criar uma nova aplicação: aceda à aplicação no painel de controlo e, em SDK keys, pressione New key para emitir outra ou Revoke para desativar a anterior. A revogação é imediata e irreversível — tudo o que ainda usar essa chave deixará de nos contactar assim que confirmar.

Etapa 3 — Definir o que vende

Ainda no painel de controlo, configure os itens que os seus utilizadores irão comprar:

  1. Crie os seus níveis de acesso (também designados por níveis ou tiers) — os níveis de acesso que o seu produto concede, como pro ou premium. Estes são os nomes que a sua aplicação irá verificar.
  2. Associe cada nível de acesso aos seus produtos na loja. Em cada loja (App Store, Google Play, Amazon, Roku, Stripe), crie os produtos de subscrição normalmente; no SubSovereign, indique-lhe "este produto da loja concede este nível de acesso." Essa associação é o que transforma uma compra num direito de acesso.
  3. Desenhe o seu paywall — o título, funcionalidades, preços e durações de teste. Como esta informação é fornecida remotamente, pode alterá-la mais tarde sem enviar uma atualização da aplicação.

Se vende através da Stripe

Configurar o seu fornecedor de pagamentos é da sua responsabilidade. Siga a documentação de instalação própria da Stripe, adicione o nosso endereço de webhook e os eventos listados abaixo no seu painel da Stripe, guarde a chave secreta Stripe na página da sua aplicação e verifique que tudo funciona com uma compra de teste antes de entrar em produção. A SubSovereign age com base nas informações que a Stripe nos fornece.

  1. No seu painel da Stripe, adicione um ponto final de webhook em <your SubSovereign server>/api/v1/webhooks/stripe?appId=<your app id>, enviando estes eventos: customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, customer.subscription.paused, customer.subscription.resumed, invoice.paid, invoice.payment_failed. A Stripe mostrará, então, o segredo de assinatura do webhook (whsec_…).
  2. Na página da sua aplicação (Aplicações → a sua aplicação → Credenciais da Loja), guarde a chave secreta Stripe e esse segredo de assinatura do webhook. Sem o segredo de assinatura, cada mensagem da Stripe é recusada.
  3. Assim que a sua aplicação estiver ligada (Etapa 4), teste-a no modo de teste da Stripe: uma compra de teste deve ativar o acesso do cliente, e cancelá-la imediatamente no painel da Stripe deve desativá-lo. Um cancelamento no final do período mantém o acesso até à data final — isso está correto, não é um erro.

Se a página da sua aplicação apresentar "Não foi possível ligar ao Stripe para esta aplicação.", a Stripe recusou a chave secreta guardada lá, ou nenhuma foi guardada — até que isso seja corrigido, os cancelamentos e os pagamentos falhados não alteram o acesso dos seus clientes.

Etapa 4 — Adicionar o SDK à sua aplicação

Integre o SDK na sua aplicação e aponte-o para o seu servidor. A estrutura é idêntica em todas as plataformas — siga o guia para a sua:

Cada um configura o SDK uma vez com a sua apiKey, appId, o baseUrl do servidor e um userId estável para o utilizador autenticado (utilize o mesmo ID em todos os locais para que o acesso siga o utilizador entre dispositivos).

Etapa 5 — Verificar o acesso e lançar

Com o SDK configurado, a sua aplicação faz duas coisas:

  • No lançamento, pergunta o que o utilizador tem e desbloqueia em conformidade (o guia do Android mostra isto como checkEntitlements(); todos os SDKs têm o equivalente).
  • Após uma compra, envie o recibo ao SubSovereign para que o servidor valide a compra com a loja e conceda o nível de acesso — depois verifique novamente e desbloqueie.

É uma integração funcional. Antes de lançar, uma lista de verificação rápida:

  • Servidor implementado num alojamento no Reino Unido/UE, migração executada e acessível a partir da sua aplicação.
  • Aplicação criada; chave de API guardada em segurança; a aplicação aponta para o seu baseUrl.
  • Níveis de acesso definidos e associados a produtos reais nas lojas que suporta.
  • Faturação das lojas (Google Play / StoreKit / Amazon / Roku / Stripe) a funcionar na sua aplicação.
  • Stripe: ponto final de webhook adicionado com os eventos acima, chave secreta e segredo de assinatura do webhook guardados, uma compra de teste vista a ativar o acesso e um cancelamento imediato visto a desativá-lo.
  • Verificação de direitos de acesso no lançamento; validação do recibo após a compra; ambos testados num dispositivo real com uma compra (sandbox) real.
  • Consentimento RGPD registado onde o recolher.

Onde ir a seguir

Also in:EnglishDeutschEspañolFrançaisहिन्दीItaliano한국어NederlandsPolskiPortuguês