# Configurar RevenueCat Guía para activar suscripciones y compras en la app después de que la CLI generó el proyecto. --- ## Lo que la CLI ya hizo por ti | Ya listo | Lo que falta | |----------|--------------| | Instaló `purchases_flutter` | Crear cuenta en RevenueCat | | Configuró las claves en `.env` (test/iOS prod/Android prod) | Crear Productos, Entitlements y Offerings en el panel RC | | Generó el código del paywall y del repositorio de suscripciones | Registrar la URL del webhook en el panel RC | | Firebase: desplegó la Cloud Function del webhook | — | | Supabase: desplegó la Edge Function del webhook | — | > Las claves quedan en `.env` en la raíz (fuente de verdad) y reflejadas en `.vscode/launch.json` + `Makefile`. Todos en `.gitignore` — nunca van al repositorio. ### ¿Qué clave usar? La CLI pregunta **tres claves opcionales** (al menos una es obligatoria): | Variable | Prefijo | Uso | |---|---|---| | `RC_TEST_KEY` | `test_` | Test Store. **Una sola clave**, sirve para iOS+Android. Usada automáticamente en simulador/emulador. | | `RC_IOS_PROD_KEY` | `appl_` | App Store (Sandbox + Producción). Usada automáticamente en iPhone físico. | | `RC_ANDROID_PROD_KEY` | `goog_` | Google Play (Sandbox + Producción). Usada automáticamente en Android físico. | `kasy run` elige la clave correcta según el dispositivo. Forzar manualmente: `kasy run --rc=test` o `kasy run --rc=prod`. --- ## Paso 1 — Crear cuenta y proyecto en RevenueCat 1. Accede a [app.revenuecat.com](https://app.revenuecat.com) → crea una cuenta gratuita 2. Crea un proyecto → ponle un nombre (ej: nombre de tu app) --- ## Paso 2 — Crear la app en RevenueCat Dentro del proyecto: **Para empezar (Test Store — sin Apple/Google)** Project → Apps → **+ Add app** → selecciona **Test Store** → copia la clave `test_xxx`. Pega esa misma clave cuando la CLI la solicite tanto para iOS como para Android (o actualiza manualmente los archivos si el proyecto ya existía). **Para producción** Crea una app separada por plataforma: - **App Store** → clave empieza con `appl_` - **Google Play** → clave empieza con `goog_` > ⚠️ **Regla crítica:** el tipo de app y el prefijo de clave deben coincidir. `Test Store` → `test_`, `App Store` → `appl_`, `Google Play` → `goog_`. Usar la clave incorrecta causa `INVALID_CREDENTIALS`. --- ## Paso 3 — Crear Productos, Entitlements y Offerings Puedes hacerlo desde el panel o pedirle a Claude con el MCP de RevenueCat ("Crea un producto `premium_monthly`, entitlement `premium_access` y offering `default`"). **Desde el panel RC** (misma URL para todos los proyectos): 1. [app.revenuecat.com](https://app.revenuecat.com) → tu proyecto → **Products** → `+ New` - Crea los planes (ej: `premium_monthly`, `premium_annual`) - Los IDs deben ser **idénticos** a los que crearás en App Store / Google Play 2. **Entitlements** → `+ New` - Crea `premium_access` → haz clic en el entitlement → **Attach** → selecciona los productos 3. **Offerings** → `+ New` - Crea `default` → entra al offering → `+ Add package` → selecciona los productos > **Sobre los IDs de productos:** deben ser idénticos carácter por carácter. `premium_monthly` en App Store y `premium_monthly` en RC — cualquier diferencia y el producto no aparece en el paywall. --- ## Paso 4 — Configurar el webhook El webhook mantiene la tabla `subscriptions` de tu base de datos actualizada en cada compra, renovación o cancelación. **La URL de la función ya fue desplegada por la CLI. Solo necesitas registrarla en RevenueCat.** Encuentra la URL de la función: | Backend | Dónde encontrar la URL | |---------|------------------------| | **Supabase** | `https://TU_PROJECT_REF.supabase.co/functions/v1/revenuecat-webhook` | | **Firebase** | [Firebase Console → Functions](https://console.firebase.google.com/project/_/functions) → `subscriptions-revenuecatWebhook` → copia la URL | Regístrala en RevenueCat: 1. [app.revenuecat.com](https://app.revenuecat.com) → tu proyecto → **Integrations** → **Webhooks** → `+ Add webhook` 2. Rellena: | Campo | Qué poner | |-------|-----------| | **Webhook name** | Cualquier nombre (ej: `firebase` o `supabase`) | | **Webhook URL** | La URL de la función de arriba | | **Authorization header value** | `Bearer ` + el valor de `REVENUECAT_WEBHOOK_KEY` (ej: `Bearer rc_wh_abc123`) | | **Environment** | `Both Production and Sandbox` | | **Events filter** | `All apps` / `All events` | 3. Haz clic en **Send test event** — si devuelve `200 OK`, está funcionando. > ⚠️ **Header de autorización:** el campo debe contener `Bearer ` seguido de tu token — incluyendo el espacio. La función rechaza cualquier header que no siga ese formato. --- ## Paso 5 — iOS: configurar en App Store Connect Necesario cuando salgas del Test Store y quieras probar con compras reales en iPhone. **Costo:** USD $99/año (Apple Developer Program) Sigue exactamente este orden — omitir cualquier paso hace que los productos no aparezcan. **1. Crear la cuenta Apple Developer** [developer.apple.com](https://developer.apple.com) → crea la cuenta y paga los USD $99/año. **2. Configurar negocios — obligatorio para que el Sandbox funcione** > ⚠️ **Este es el paso más ignorado y el más bloqueante.** Sin él, el Sandbox devuelve lista vacía de productos aunque hayas hecho todo bien: cuenta RC, producto creado, Sandbox Tester configurado en el iPhone. Nada funciona. [appstoreconnect.apple.com](https://appstoreconnect.apple.com) → menú superior → **Agreements, Tax, and Banking**: - Acepta el **Paid Applications Agreement** (contrato de asociación con Apple) - Registra la **cuenta bancaria** donde recibirás los pagos - Completa los **formularios fiscales** (país, tipo de persona física o jurídica) - Acepta las **conformidades** requeridas - Si vas a vender en Europa: completa la información pública adicional exigida Después de completar todo, **espera de 4 a 6 horas** para que las configuraciones se propaguen. Solo después de ese tiempo el Sandbox funcionará correctamente. Intentar antes devuelve lista vacía o errores genéricos. **3. Crear la app en App Store Connect** [appstoreconnect.apple.com](https://appstoreconnect.apple.com) → **My Apps** → `+` → **New App** → usa el mismo Bundle ID del proyecto Flutter. **4. Crear las suscripciones** App Store Connect → tu app → **Monetización** → **Suscripciones**: a) **Crear el grupo de suscripciones** (ej: "Premium") — todas las suscripciones quedan dentro de un grupo. b) **Configurar el período de gracia** (opcional pero recomendado): haz clic en **Período de gracia** → **Editar** → elige la duración. Recomendado: **3 días** para la mayoría de los apps. Sirve para mantener el acceso del suscriptor durante fallas temporales de pago antes de cancelar. c) **Crear los productos** dentro del grupo: - Agrega los productos con los mismos IDs de RevenueCat (ej: `subscription_monthly_01`) - Completa: precio, duración, idioma de la suscripción y captura de pantalla d) **Configurar el idioma del grupo** — paso que mucha gente olvida: Dentro del grupo → sección **Idioma** → `+` → selecciona el idioma (ej: Inglés EE.UU.) → completa **Nombre de visualización del grupo** (ej: `premium`) → guarda. > ⚠️ **Sin este paso los productos quedan atascados en "Missing Metadata"** y nunca avanzan a "Preparar para envío" ni "Listo para enviar", incluso con precio, idioma y captura de pantalla de la suscripción completados. El idioma del **grupo** es distinto al idioma de cada suscripción individual. e) **Captura de pantalla de la suscripción** (obligatoria para envío a revisión): Toma un screenshot del paywall de tu app corriendo en el simulador iOS o en el iPhone físico (`make run-ios` → abre la pantalla premium). Usa esa imagen en el campo **Captura de pantalla** de cada suscripción. El campo **Notas para el equipo de revisión** es opcional — puedes describir brevemente el producto. Después de completar todo y configurar el idioma del grupo, el estado sale de **Missing Metadata** → **Preparar para envío** → **Listo para enviar**. Cualquiera de los dos últimos ya está correcto. **5. Crear la app en RevenueCat como App Store** [app.revenuecat.com](https://app.revenuecat.com) → tu proyecto → **Apps** → `+ Add app` → **App Store** → copia la clave `appl_xxx`. Pégala en el `.env` de la raíz: ```env RC_IOS_PROD_KEY=appl_xxxxxxxxxxxxxxx ``` `kasy run` usa esta clave automáticamente en iPhone físico (el simulador sigue con `RC_TEST_KEY`). **6. Crear Sandbox Tester — obligatorio para probar en iPhone físico** [appstoreconnect.apple.com](https://appstoreconnect.apple.com) → **Users and Access** → pestaña **Sandbox** → **Testers** → `+` Crea un correo que **no tenga ninguna cuenta Apple asociada** (un Gmail nuevo funciona bien). El correo debe ser accesible — Apple envía un código de verificación para confirmar la cuenta. > El Sandbox Tester **no es** una cuenta Apple ID real. Es una cuenta exclusiva para pruebas que solo funciona en el entorno Sandbox. Sin ella, el iPhone pide el Apple ID normal y la compra va a producción. **7. Activar Developer Mode en el iPhone (iOS 16+)** Obligatorio para ejecutar apps directamente desde Xcode/terminal en el dispositivo físico. iPhone → **Ajustes** → **Privacidad y Seguridad** → desplázate hasta el final → **Modo Desarrollador** → actívalo → el iPhone reinicia para confirmar. > Si la opción no aparece, conecta el iPhone al Mac con Xcode abierto al menos una vez — eso desbloqueará el Modo Desarrollador. **8. Conectar la cuenta Sandbox en el iPhone** En iPhones modernos (iOS 16+), la cuenta Sandbox está dentro de la sección Desarrollador: iPhone → **Ajustes** → desplázate hasta el final → **Desarrollador** → desplázate hasta el final de la página → **Cuenta Sandbox** → **Iniciar sesión** → usa el correo y contraseña del Sandbox Tester creado. > En versiones anteriores de iOS, el camino era Ajustes → App Store → Cuenta Sandbox. En iPhones actuales el camino correcto es a través del menú Desarrollador como se indica arriba. **9. Configurar la clave P8 (recomendado para sandbox, obligatorio para producción)** [appstoreconnect.apple.com](https://appstoreconnect.apple.com) → **Users and Access** → **Integrations** → **In-App Purchase** → `+` → descarga el `.p8` → pégalo en RevenueCat en **App Settings** → **In-App Purchase Key**. > Solo puedes descargar la P8 una vez. Guárdala en un lugar seguro. **9. Ejecutar en iPhone físico** ```bash make run-ios ``` Haz una compra — aparece el modal real de Apple. Con la cuenta Sandbox activa, la compra no genera ningún cargo. --- ## Paso 6 — Android: configurar en Google Play Console Necesario cuando salgas del Test Store y quieras probar con compras reales en Android. **Costo:** USD $25 (pago único) **1. Crear la cuenta Google Play Developer** [play.google.com/console](https://play.google.com/console) → crea la cuenta y paga los USD $25. **2. Configurar el perfil de pago** Google Play Console → **Configuración** (menú lateral principal) → **Cuenta de desarrollador** → **Perfil de pagos** → completa nombre legal, dirección y datos fiscales. **3. Crear la app** Google Play Console → **Crear app** → completa nombre, idioma y categoría. **4. Publicar en el track de Pruebas Internas — obligatorio para crear suscripciones** **Pruebas** → **Pruebas internas** → crea el release → sube un APK/AAB firmado → publica. > La app no necesita estar completa — una versión de desarrollo firmada es suficiente. **5. Crear las suscripciones** Google Play Console → tu app → **Monetizar** → **Suscripciones** → `+ Crear suscripción`: - Crea los productos con los mismos IDs de RevenueCat - Déjalos en estado `Activo` **6. Crear la Service Account (credencial de RevenueCat para Google)** a) [console.cloud.google.com](https://console.cloud.google.com) → selecciona el proyecto del app → **APIs y servicios** → **Biblioteca** → activa: - **Google Play Android Developer API** - **Google Play Developer Reporting API** b) **IAM y administración** → **Cuentas de servicio** → **+ Crear cuenta de servicio**: - Nombre: `revenuecat-service` (o cualquier nombre) - Roles: **Editor de Pub/Sub** + **Lector de supervisión** - Haz clic en **Listo** c) Haz clic en la cuenta creada → pestaña **Claves** → **Agregar clave** → **Crear nueva clave** → **JSON** → descarga el archivo. d) Google Play Console → **Configuración** → **Usuarios y permisos** → **Invitar nuevos usuarios**: - Correo: el correo de la Service Account (visible en Cloud Console) - Permisos: **Gestionar pedidos y suscripciones** + **Gestionar informes financieros** - Guarda > Después de configurar, espera hasta 36 horas para que las credenciales se propaguen. Errores 503/521 en RC durante ese período son normales. **7. Configurar en RevenueCat con credenciales de Google** [app.revenuecat.com](https://app.revenuecat.com) → tu proyecto → **Apps** → `+ Add app` → **Google Play** → sube el archivo JSON → copia la clave `goog_xxx`. Pégala en el `.env` de la raíz: ```env RC_ANDROID_PROD_KEY=goog_xxxxxxxxxxxxxxx ``` `kasy run` usa esta clave automáticamente en Android físico (el emulador sigue con `RC_TEST_KEY`). **8. Agregar License Tester — obligatorio para probar en el dispositivo** Google Play Console → **Configuración** → **License testing** → agrega el correo de la cuenta Google que está en el dispositivo Android de prueba. > Usa solo **una cuenta Google** en el dispositivo — varias cuentas causan fallas en las compras. **9. Ejecutar en dispositivo Android** ```bash make run-android ``` Haz una compra — aparece el modal real de Google Play. En Sandbox, las suscripciones mensuales se renuevan cada 5 minutos. --- ## Checklist rápido ### Test Store (sin Apple/Google) - [ ] Cuenta y proyecto creados en RevenueCat - [ ] App creada como **Test Store** — clave `test_xxx` pegada - [ ] Productos, Entitlements y Offerings configurados en RC - [ ] Webhook registrado en RC y probado (`200 OK`) - [ ] La compra de prueba activa el entitlement correctamente ### iOS (App Store Connect) - [ ] Apple Developer Program activo (USD $99/año) - [ ] Paid Applications Agreement firmado - [ ] Cuenta bancaria validada en App Store Connect - [ ] App creada en App Store Connect con Bundle ID correcto - [ ] Grupo de suscripciones creado con idioma configurado (sin esto los productos quedan en "Missing Metadata") - [ ] Suscripciones creadas con IDs idénticos a RevenueCat, con precio, idioma y captura de pantalla completos - [ ] Estado de las suscripciones en **Listo para enviar** - [ ] App creada en RC como **App Store** — clave `appl_xxx` actualizada en los archivos - [ ] Sandbox Tester creado en App Store Connect → Users and Access → Sandbox (correo sin cuenta Apple) - [ ] Developer Mode activo en el iPhone (Ajustes → Privacidad y Seguridad → Modo Desarrollador) - [ ] Cuenta Sandbox conectada en iPhone (Ajustes → Desarrollador → Cuenta Sandbox) - [ ] Clave P8 configurada en RC - [ ] Compra probada en iPhone físico ### Android (Google Play) - [ ] Google Play Developer activo (USD $25) - [ ] Perfil de pago configurado - [ ] App creada y publicada en el track de Pruebas Internas - [ ] Suscripciones creadas con IDs idénticos a RevenueCat - [ ] APIs activadas en Google Cloud Console - [ ] Service Account creada, JSON descargado e invitada en Google Play - [ ] JSON de la Service Account subido a RC — clave `goog_xxx` actualizada en los archivos - [ ] License Tester agregado en Google Play Console - [ ] Solo una cuenta Google en el dispositivo de prueba - [ ] Compra probada en dispositivo Android físico --- ## Errores comunes **`INVALID_CREDENTIALS`** — el tipo de app en RC y el prefijo de la clave no coinciden. `Test Store` requiere clave `test_`, `App Store` requiere `appl_`, `Google Play` requiere `goog_`. **Productos no aparecen en el paywall** — los IDs no son idénticos entre la tienda y RC, o el Paid Applications Agreement no está firmado (iOS), o la app no está publicada en el track interno (Android). **Sandbox devuelve lista vacía (iOS)** — configuración de negocios incompleta en App Store Connect → Agreements, Tax, and Banking. Verifica: Paid Applications Agreement aceptado, cuenta bancaria registrada, formularios fiscales completados, conformidades aceptadas. Después de completar todo, espera de 4 a 6 horas antes de probar. Verifica con: ```bash kasy doctor ``` El `kasy doctor` muestra una sección **RevenueCat** automáticamente cuando el proyecto usa la feature. Ejemplo de salida: ``` RevenueCat ✓ Claves de API configuradas (iOS + Android) ⚠ Usando claves Test Store (test_) — reemplaza por appl_ y goog_ para producción ✓ URL del webhook (pega en RevenueCat → Integrations → Webhooks): https://TU_PROJECT_REF.supabase.co/functions/v1/revenuecat-webhook ``` > Para proyectos Firebase, el `kasy doctor` indica dónde encontrar la URL en Firebase Console en lugar de mostrarla directamente.