SubSovereign
← All guides

Cómo empezar con SubSovereign

Esta guía te lleva desde cero hasta una verificación de suscripción funcional en tu app. Es la compañera práctica de Cómo funciona SubSovereign — léela primero si quieres entender los conceptos.

Hay cinco pasos: configurar el servidor → crear tu app → definir lo que vendes → añadir el SDK → verificar el acceso. Calcula una tarde para el primero; el resto son rápidos.

Paso 1 — Configurar el servidor

SubSovereign es self-hosted, por lo que el primer paso es ejecutar el backend en tu propia infraestructura. Se trata de un servicio Node.js/TypeScript respaldado por PostgreSQL (para entitlements, eventos y consentimiento) y Redis (para una caché rápida de entitlements).

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 un despliegue gestionado hay una configuración lista para Northflank (backend/northflank.yml), pero cualquier host que ejecute Node + PostgreSQL + Redis funciona — la idea es que sea tuyo. Una vez en marcha, anota su dirección; esa será el baseUrl al que tus apps se conectarán (por ejemplo, https://subs.tudominio.com).

Consejo: mantén el servidor alojado en el Reino Unido/UE. La soberanía y el GDPR son el punto clave — no lo pierdas en el despliegue.

Paso 2 — Crear tu app en el panel de control

Abre el panel de control y crea un app — uno por cada producto que distribuyas (tu app de Android e iOS pueden ser el mismo registro o separados; tú decides). Al crear un app obtienes dos elementos que necesitarás:

  • un appId — identifica este app en el servidor, y
  • una clave de API — la credencial que usa tu app para autenticar las llamadas al SDK.

🚩 Copie la clave de API en el momento en que aparezca y guárdela en un lugar seguro. Se muestra una sola vez. Solo conservamos un hash de la misma, por lo que ya no podrá volver a visualizarse. Si la pierde o se filtra, no necesita crear una nueva aplicación: abra la aplicación en el panel de control, vaya a SDK keys y pulse New key para generar otra, o Revoke para desactivar la anterior. La revocación es inmediata y no puede deshacerse — cualquier servicio que aún utilice esa clave dejará de comunicarse con nosotros en el momento en que confirme la acción.

Paso 3 — Definir lo que vendes

Todavía en el panel, configura los elementos que tus usuarios comprarán realmente:

  1. Crea tus niveles de acceso (también llamados niveles o tiers) — los niveles de acceso que concede tu producto, como pro o premium. Estos son los nombres que tu app verificará.
  2. Vincula cada nivel de acceso a tus productos en la tienda. En cada tienda (App Store, Google Play, Amazon, Roku, Stripe) creas los productos de suscripción como de costumbre; en SubSovereign le indicas "este producto de la tienda concede este nivel de acceso". Esa asignación es lo que convierte una compra en un entitlement.
  3. Diseña tu paywall — el titular, las funciones, los precios y las duraciones de prueba. Como esto se sirve de forma remota, puedes cambiarlo más tarde sin necesidad de actualizar la app.

Si vendes a través de Stripe

Configurar tu proveedor de pagos es tu responsabilidad. Sigue la propia documentación de instalación de Stripe, añade nuestra dirección webhook y los eventos listados a continuación en tu panel de Stripe, guarda tu clave secreta de Stripe en la página de tu aplicación y comprueba que todo funciona con una compra de prueba antes de lanzar tu producto. SubSovereign actúa según lo que Stripe nos comunica.

  1. En tu panel de Stripe, añade un punto final webhook en <your SubSovereign server>/api/v1/webhooks/stripe?appId=<your app id>, enviando estos eventos: customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, customer.subscription.paused, customer.subscription.resumed, invoice.paid, invoice.payment_failed. Stripe mostrará entonces el secreto de firma del webhook (whsec_…) de ese punto final.
  2. En la página de tu aplicación (Aplicaciones → tu aplicación → Credenciales de la tienda), guarda tu clave secreta de Stripe y ese secreto de firma del webhook. Sin el secreto de firma, cada mensaje de Stripe será rechazado.
  3. Una vez que tu aplicación esté conectada (Paso 4), pruébala en el modo de prueba de Stripe: una compra de prueba debería activar el acceso del cliente, y cancelarla inmediatamente en el panel de Stripe debería desactivarlo. Si la cancelas al final del periodo, el acceso se mantendrá hasta la fecha de finalización; eso es correcto, no es un fallo.

Si la página de tu aplicación muestra "No podemos conectar con Stripe para esta aplicación", Stripe ha rechazado la clave secreta guardada allí o no hay ninguna guardada. Hasta que eso se solucione, las cancelaciones y los pagos fallidos no cambiarán el acceso de tus clientes.

Paso 4 — Añadir el SDK a tu app

Incorpora el SDK a tu app y apúntalo a tu servidor. La estructura es idéntica en todas las plataformas — sigue la guía correspondiente a la tuya:

Cada uno configura el SDK una vez con tu apiKey, appId, el baseUrl de tu servidor y un userId estable para el usuario autenticado (usa el mismo ID en todas partes para que el acceso siga al usuario entre dispositivos).

Paso 5 — Verificar el acceso y lanzar

Con el SDK configurado, tu app hace dos cosas:

  • Al iniciar, pregunta qué tiene el usuario y desbloquea en consecuencia (la guía de Android lo muestra como checkEntitlements(); todos los SDK tienen su equivalente).
  • Tras una compra, envía el recibo a SubSovereign para que el servidor valide la compra con la tienda y conceda el nivel de acceso — luego vuelve a verificar y desbloquea.

Eso es una integración funcional. Antes de lanzar, revisa esta lista rápida:

  • Servidor desplegado en alojamiento del Reino Unido/UE, migración ejecutada y accesible desde tu app.
  • App creada; clave de API guardada de forma segura; la app apunta a tu baseUrl.
  • Niveles de acceso definidos y vinculados a productos reales en las tiendas que soportes.
  • Facturación de la tienda (Google Play / StoreKit / Amazon / Roku / Stripe) funcionando en tu app.
  • Stripe: punto final webhook añadido con los eventos anteriores, clave secreta y secreto de firma del webhook guardados, una compra de prueba vista activando el acceso y una cancelación inmediata vista desactivándolo.
  • Verificación de entitlement al iniciar; validación del recibo tras la compra; ambos probados en un dispositivo real con una compra (en entorno de pruebas).
  • Consentimiento GDPR registrado donde lo recojas.

Dónde seguir

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