SubSovereign
← All guides

Guida introduttiva a SubSovereign

Questa guida ti accompagna dalla configurazione iniziale a un controllo delle sottoscrizioni funzionante nella tua app. È il complemento pratico di Come funziona SubSovereign — leggilo prima se vuoi comprendere i concetti.

Ci sono cinque passaggi: avviare il server → creare la tua app → definire cosa vendere → aggiungere l'SDK → verificare l'accesso. Per il primo passaggio, programma un pomeriggio; i successivi sono rapidi.

Passaggio 1 — Avviare il server

SubSovereign è self-hosted, quindi il primo passo è eseguire il backend sulla tua infrastruttura. Si tratta di un servizio Node.js/TypeScript basato su PostgreSQL (per diritti, eventi e consenso) e Redis (per una cache veloce dei diritti).

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

Per un deployment gestito esiste già una configurazione pronta per Northflank (backend/northflank.yml), ma puoi usare qualsiasi host che supporti Node + PostgreSQL + Redis — il punto è che sia tuo. Una volta avviato, prendi nota del suo indirizzo: è il tuo baseUrl, a cui le tue app si collegheranno (ad esempio https://subs.tuodominio.com).

Suggerimento: mantieni il server su hosting UK/EU. La sovranità e il GDPR sono il cuore del prodotto — non rinunciarci già in fase di deployment.

Passaggio 2 — Creare la tua app nella dashboard

Apri la dashboard e crea un'app — una per ogni prodotto che distribuisci (la tua app Android e quella iOS possono essere la stessa voce o separate; la scelta è tua). Creare un'app ti fornisce due elementi necessari:

  • un appId — identifica questa app lato server e
  • una chiave API — la credenziale che la tua app usa per autenticare le chiamate dell'SDK.

🚩 Copia la chiave API nel momento in cui viene visualizzata e conservala in un luogo sicuro. Viene mostrata una sola volta. Noi ne conserviamo solo un hash, quindi non sarà più possibile visualizzarla. Se la perdi o viene compromessa, non serve creare una nuova app: accedi all’app nella dashboard, vai alla sezione SDK keys e premi New key per generarne un’altra, oppure Revoke per disattivare quella precedente. La revoca è immediata e irreversibile — qualsiasi sistema che utilizzi ancora quella chiave smetterà di ricevere dati nel momento in cui confermi l’operazione.

Passaggio 3 — Definire cosa vendere

Sempre nella dashboard, configura ciò che i tuoi utenti potranno acquistare:

  1. Crea i tuoi livelli di accesso (anche detti livelli o tier) — i livelli di accesso che il tuo prodotto concede, come pro o premium. Questi sono i nomi che la tua app controllerà.
  2. Collega ogni livello di accesso ai prodotti dello store. In ogni store (App Store, Google Play, Amazon, Roku, Stripe) crei i prodotti di sottoscrizione come al solito; in SubSovereign gli dici "questo prodotto dello store concede questo livello di accesso." Questa mappatura è ciò che trasforma un acquisto in un diritto.
  3. Progetta il tuo paywall — il titolo, le funzionalità, i prezzi e le durate delle prove. Poiché viene fornito in remoto, puoi modificarlo in seguito senza dover distribuire un aggiornamento dell'app.

Se vendi tramite Stripe

Configurare il tuo fornitore di pagamenti è responsabilità tua. Segui la documentazione ufficiale di Stripe, aggiungi il nostro indirizzo webhook e gli eventi elencati qui sotto nel tuo pannello Stripe, salva la chiave segreta Stripe nella pagina della tua App e verifica che tutto funzioni con un acquisto di prova prima di andare online. SubSovereign agisce in base a ciò che Stripe ci comunica.

  1. Nel pannello Stripe, aggiungi un endpoint webhook all’indirizzo <your SubSovereign server>/api/v1/webhooks/stripe?appId=<your app id>, inviando questi eventi: customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, customer.subscription.paused, customer.subscription.resumed, invoice.paid, invoice.payment_failed. Stripe mostrerà quindi il segreto di firma webhook (whsec_…) dell’endpoint.
  2. Nella pagina della tua App (App → la tua App → Credenziali Store), salva la chiave segreta Stripe e quel segreto di firma webhook. Senza il segreto di firma, ogni messaggio di Stripe viene rifiutato.
  3. Una volta che la tua App è connessa (Passaggio 4), testala in modalità prova di Stripe: un acquisto di prova dovrebbe attivare l’accesso del cliente, mentre annullarlo immediatamente nel pannello Stripe dovrebbe disattivarlo. Un annullamento alla fine del periodo mantiene l’accesso fino alla data di scadenza: è corretto, non un errore.

Se nella pagina della tua App compare "Impossibile contattare Stripe per questa app", la chiave segreta salvata lì è stata rifiutata da Stripe oppure non è stata salvata: finché il problema non è risolto, gli annullamenti e i pagamenti non andati a buon fine non modificano l’accesso dei tuoi clienti.

Passaggio 4 — Aggiungere l'SDK alla tua app

Integra l'SDK nella tua app e punta al tuo server. La struttura è identica su tutte le piattaforme — segui la guida specifica per la tua:

Ogni guida configura l'SDK una volta sola con la tua chiave API, il tuo appId, il tuo baseUrl del server e un userId stabile per l'utente autenticato (usa lo stesso ID ovunque, così l'accesso segue l'utente tra i dispositivi).

Passaggio 5 — Verificare l'accesso e andare online

Con l'SDK configurato, la tua app fa due cose:

  • All'avvio, chiedi cosa possiede l'utente e sblocca di conseguenza (la guida Android mostra questo come checkEntitlements(); ogni SDK ha l'equivalente).
  • Dopo un acquisto, invia la ricevuta a SubSovereign affinché il server la validi con lo store e conceda il livello di accesso — poi ricontrolla e sblocca.

Ecco fatto: integrazione funzionante. Prima di distribuire, controlla la checklist:

  • Server deployato su hosting UK/EU, migrazione eseguita, raggiungibile dalla tua app.
  • App creata; chiave API salvata in sicurezza; l'app punta al tuo baseUrl.
  • Livelli di accesso definiti e collegati ai prodotti reali degli store che supporti.
  • Billing degli store (Google Play / StoreKit / Amazon / Roku / Stripe) funzionante nella tua app.
  • Stripe: endpoint webhook aggiunto con gli eventi sopra elencati, chiave segreta e segreto di firma webhook salvati, acquisto di prova che attiva l’accesso e annullamento immediato che lo disattiva.
  • Controllo dei diritti all'avvio; validazione della ricevuta dopo l'acquisto; entrambi testati su un dispositivo reale con un acquisto (sandbox) reale.
  • Consenso GDPR registrato dove lo raccogli.

Dove andare dopo

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