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 appena compare e conservala in un luogo sicuro: viene mostrata UNA SOLA VOLTA. Ne conserviamo solo un hash. Non può essere mostrata di nuovo e non è possibile emettere una chiave sostitutiva per un'app già esistente. Se la perdi, archivia quell'app e creane una nuova.

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.

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.
  • 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