Guía de onboarding de CLI

Resumen rápido

Capgo CLI ofrece un onboarding interactivo que configura las actualizaciones en vivo de tu app Capacitor. Podrás:

1. ✅ Registrar tu app en Capgo
2. 🔌 Instalar y configurar el plugin updater
3. 🚀 Desplegar tu primer live update
4. 📱 Probar la actualización en tu dispositivo

Tiempo estimado: 10-20 minutos (varía según tu velocidad de internet y el tiempo de build)

Consejo

El onboarding es totalmente reanudable: puedes salir en cualquier momento y continuar donde lo dejaste.

Iniciar el onboarding

Ejecuta el comando de onboarding con tu clave API:

npx @capgo/cli@latest init [APIKEY]

Verás el mensaje de bienvenida:

Capgo onboarding 🛫

Qué ocurre durante el onboarding

El CLI te guiará a través de 13 pasos interactivos:

Fase de configuración (pasos 1-6):

• Comprueba tu entorno de desarrollo (Xcode/Android Studio)
• Añade tu app a Capgo y crea un canal de producción
• Instala el @capgo/capacitor-updater plugin
• Inyecta el code necesario en tu app
• Activa opcionalmente el cifrado de extremo a extremo
• Elige una plataforma para probar (iOS o Android)

Fase de pruebas (pasos 7-12):

• Compila tu app y ejecútala en un dispositivo/simulador
• Realiza un cambio visible de code (automático o manual)
• Sube el bundle actualizado a Capgo
• Mira cómo aparece el live update en tu dispositivo en tiempo real

Completado (Paso 13):

• ¡Tu app está lista para actualizaciones en vivo! 🎉

El proceso de onboarding de 13 pasos

Paso 1: Verificar requisitos previos

El CLI verifica tu entorno de desarrollo para asegurarse de que tienes las herramientas necesarias instaladas.

Qué se verifica:

• Xcode (solo macOS) - para desarrollo de iOS
• SDK para Android - para desarrollo de Android

Resultados posibles:

✅ Ambos entornos encontrados:

✅ Xcode detected - iOS development ready
✅ Android SDK detected - Android development ready

⚠️ Ningún entorno encontrado:

⚠️ Xcode not found
⚠️ Android SDK not found
❌ No development environment detected

📱 To develop mobile apps with Capacitor, you need:
   • For iOS: Xcode (macOS only) - https://developer.apple.com/xcode/
   • For Android: Android Studio - https://developer.android.com/studio

Preguntas que podrían hacerte:

Precaución

Si no se detecta un entorno de desarrollo, se te pedirá que confirmes si deseas continuar. Se recomienda instalar al menos una plataforma antes de proceder.

Paso 2: Añade tu app

El CLI iniciará sesión en Capgo y añadirá tu app a tu cuenta.

(spinner) Running: npm @capgo/cli@latest login ***
Login Done ✅

❓ Add {appId} in Capgo?

Si tu app ID ya está en uso:

El CLI sugerirá alternativas:

❌ App ID "com.example.app" is already taken
💡 Here are some suggestions:
   1. com.example.app2
   2. com.example.app3
   3. com.example.app.new
   4. com.example.app.app

❓ What would you like to do?

Puedes elegir una sugerencia o introducir un app ID personalizado.

Nota

Los app ID deben seguir la notación de dominio inverso (p. ej., com.example.myapp)

Paso 3: Crea un canal de producción

Los canales te permiten gestionar diferentes flujos de actualizaciones para tu app.

❓ Create default channel production for {appId} in Capgo?

Consejo

¡No te preocupes! Esto es solo para pruebas locales durante el onboarding. Crear un canal de “producción” no significa que tus actualizaciones se publiquen inmediatamente para los clientes. Tienes el control total sobre cuándo se despliegan las actualizaciones. Selecciona Sí a menos que tengas requisitos específicos de canal.

Si seleccionas Sí:

(spinner) Running: npm @capgo/cli@latest channel add production {appId} --default
Channel add Done ✅  (or "Channel already added ✅")

Se creará un canal de producción y se establecerá como predeterminado. Esta es la opción recomendada para la mayoría de los usuarios.

Si seleccionas No:

If you change your mind, run it for yourself with: "npm @capgo/cli@latest channel add production {appId} --default"

Deberás crear y configurar los canales manualmente más adelante. Alternativamente, puedes:

• Establecer el canal en tu capacitor.config.ts archivo
• Usar el JavaScript setChannel() método para establecer dinámicamente el canal
• Configurar los canales más adelante desde la consola web de Capgo

Paso 4: Instala el plugin Updater

El CLI instalará el @capgo/capacitor-updater plugin compatible con tu versión de Capacitor.

❓ Automatic Install "@capgo/capacitor-updater" dependency in {appId}?

Compatibilidad de versión:

• Capacitor 5: Instala @capgo/capacitor-updater v5
• Capacitor 6: Instala @capgo/capacitor-updater v6
• Capacitor 7: Instala @capgo/capacitor-updater v7
• Capacitor 8+: Instala la última versión

Precaución

Capgo solo admite Capacitor v5 o superior. Si usas una versión anterior, primero debes actualizarla.

Opción de actualizaciones instantáneas:

Tras la instalación, se te pedirá:

❓ Do you want to set instant updates in {appId}?
   Read more: https://capgo.app/docs/live-updates/update-behavior/#applying-updates-immediately

Consejo

¿Qué son las actualizaciones instantáneas? Con las actualizaciones instantáneas activadas, tu app aplica las actualizaciones de inmediato al pasar a segundo plano y volver a abrirse. Esto funciona sin problemas porque Capgo puede distribuir actualizaciones en todo el mundo en menos de 300 ms. Sin esta opción (modo estándar), las actualizaciones se descargan en segundo plano y se aplican en el siguiente reinicio de la app. Las actualizaciones instantáneas son ideales para iterar más rápido durante el desarrollo y corregir errores críticos en producción.

Si seleccionas Sí:

• Las actualizaciones se configurarán para aplicarse inmediatamente cuando la app pase a segundo plano y se vuelva a abrir
• autoUpdate: 'always' y autoSplashscreen: true se añadirá a tu config
• @capacitor/splash-screen se instalará si falta, con launchAutoHide: false
• Tu capacitor.config.ts se actualizará automáticamente
• Actualizaciones delta se mantendrá activado. Aplicación instantánea (always, atInstall, onLaunch) debería seguir usando npx @capgo/cli@latest bundle upload --delta así solo se descargan los archivos cambiados y el usuario no espera un zip completo

Si seleccionas No:

• Las actualizaciones usarán el comportamiento estándar (descarga en segundo plano, aplicar al reiniciar)
• Siempre puedes activar las actualizaciones instantáneas más tarde modificando tu capacitor.config.ts

Paso 5: Añadir integración Code

CLI inyectará automáticamente el code necesario en el archivo principal de tu aplicación.

❓ Automatic Add "CapacitorUpdater.notifyAppReady()" code and import in {appId}?

Qué se añade:

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

Detección del tipo de proyecto:

• Nuxt.js: Crea plugins/capacitorUpdater.client.ts
• Otros frameworks: Añade a tu archivo de entrada principal

Consejo

Si la inyección automática falla, puedes añadir code manualmente a tu archivo principal de la aplicación:

Para Nuxt.js: Crear plugins/capacitorUpdater.client.ts:

import { CapacitorUpdater } from '@capgo/capacitor-updater'

export default defineNuxtPlugin(() => {
  CapacitorUpdater.notifyAppReady()
})

Para otros frameworks: Añade a tu archivo de entrada principal (p. ej., main.ts, index.js, App.tsx):

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

Coloca este code después de tus imports y antes de la inicialización de tu app. Para más detalles, consulta Guía para añadir una app.

Paso 6: Configura el cifrado (opcional)

La cifrado de extremo a extremo añade una capa de seguridad extra a tus actualizaciones.

🔐 End-to-end encryption
   ✅ Use this for: Banking, healthcare, or apps with legal encryption requirements
   ⚠️  Note: Makes debugging harder - skip if you don't need it

❓ Enable end-to-end encryption for {appId} updates?

Nota

El cifrado solo está disponible en Capacitor v6 o superior.

Si activas el cifrado, CLI hará lo siguiente:

1. Generar claves de cifrado
2. Ofrecer sincronizar tu configuración de Capacitor

Paso 7: Selecciona la plataforma

Elige la plataforma con la que quieres probar durante el onboarding.

📱 Platform selection for onboarding
   This is just for testing during onboarding - your app will work on all platforms

❓ Which platform do you want to test with during this onboarding?
   Options:
   - iOS
   - Android

Consejo

Esto solo afecta al proceso de onboarding. Tu app final soportará todas las plataformas.

Paso 8: Compila tu proyecto

El CLI compilará tu app y la sincronizará con Capacitor.

❓ Automatic build {appId} with "npm run build"?

Qué sucede:

1. Detecta el tipo de proyecto
2. Ejecuta tu script de build
3. Ejecuta npx cap sync {platform}

Si falta el script de build:

Se te preguntará si quieres omitir el build o añadir un script de build a tu package.json.

Paso 9: Ejecutar en un dispositivo

Prueba la versión inicial de tu app en un dispositivo o simulador.

❓ Run {appId} on {PLATFORM} device now to test the initial version?

Si seleccionas Sí:

(spinner) Running: npx cap run {platform}
(device picker appears)
App started ✅
📱 Your app should now be running on your {platform} device with Capgo integrated
🔄 This is your baseline version - we'll create an update next

Paso 10: Realizar un cambio de prueba

Ahora es el momento de probar el sistema de actualizaciones de Capgo haciendo un cambio visible.

🎯 Now let's test Capgo by making a visible change and deploying an update!

❓ How would you like to test the update?
   Options:
   - Auto: Let Capgo CLI make a visible change for you
   - Manual: I'll make changes myself

Modo automático: CLI modificará tus archivos automáticamente para añadir un banner de prueba visible o un cambio visible.

Modo manual: Tú realizas tus propios cambios (ej. cambiar texto, colores o añadir elementos).

Gestión de versiones:

❓ How do you want to handle the version for this update?
   Options:
   - Auto: Bump patch version ({currentVersion} → {nextVersion})
   - Manual: I'll provide the version number

Build con cambios:

❓ Build {appId} with changes before uploading?

Consejo

Si necesitas hacer el build manualmente en otra terminal, selecciona “No”, hazlo tú mismo y continúa.

Paso 11: Subir bundle

Sube tu bundle de app actualizado a Capgo.

❓ Upload the updated {appId} bundle (v{version}) to Capgo?

El CLI ejecuta:

npx @capgo/cli@latest bundle upload

Consejo

Delta updates with instant updates: Si habilitaste las actualizaciones instantáneas en el paso 4, CLI te preguntará automáticamente si deseas habilitar las actualizaciones delta. Las actualizaciones delta envían solo los archivos que cambiaron entre versiones, en lugar de todo el bundle. Como normalmente solo cambian unos pocos archivos entre actualizaciones, esto hace que las descargas sean mucho más rápidas. Selecciona Sí para la mejor experiencia con las actualizaciones instantáneas.

Solicitud de actualizaciones delta (si se habilita un modo de aplicación instantánea):

💡 Instant updates are enabled in your config
   Delta updates send only changed files instead of the full bundle

❓ Enable delta updates for this upload? (Recommended with instant updates)

Precaución

Para monorepos, es posible que necesites proporcionar rutas adicionales a tu package.json y node_modules.

Éxito:

✅ Update v{version} uploaded successfully!
🎉 Your updated bundle is now available on Capgo

Paso 12: Probar la actualización en el dispositivo

¡Es hora de ver la actualización en acción!

🧪 Time to test the Capgo update system!
📱 Go to your device where the app is running

Para actualizaciones instantáneas:

🔄 IMPORTANT: Background your app (swipe up/press home button) and then reopen it
⏱️  The update should be downloaded and applied automatically

Para actualizaciones estándar:

📱 With standard updates, you will need to:
   1. Background the app (swipe up/press home button) to start download
   2. Wait a few seconds for download to complete
   3. Background and foreground again to see the update

Monitorea los logs:

❓ Monitor Capgo logs to verify the update worked?

Si seleccionas Sí, verás los logs en vivo de tu dispositivo mostrando el proceso de actualización.

Paso 13: Finalización

Welcome onboard ✈️!

¡Felicidades! Has configurado correctamente las actualizaciones en vivo de Capgo para tu app.

Lo que has logrado

Tras completar el onboarding, tienes:

✅ App registrada

Tu app está registrada en Capgo con un canal de producción

✅ Plugin instalado

El plugin Capacitor Updater está instalado y configurado

✅ Code integrado

La integración code se ha añadido a tu app

✅ Actualización probada

Has desplegado con éxito y recibido un live update

Flujo de trabajo diario

Para actualizaciones posteriores, usa:

npm run build
npx @capgo/cli@latest bundle upload --channel=production

Para más opciones de despliegue, consulta Desplegar un Live Update.

Reanudar el onboarding

Si sales del proceso de onboarding, puedes retomarlo en cualquier momento:

npx @capgo/cli@latest init [APIKEY]

Verás:

You have already got to the step {stepNumber}/13 in the previous session
❓ Would you like to continue from where you left off?

Consejo

El progreso se guarda localmente, por lo que puedes salir y reanudar el onboarding con seguridad.

Solución de problemas

Sin entorno de desarrollo

Problema: No se detecta Xcode ni Android SDK.

Solución:

• Para iOS: Instalar Xcode (solo macOS)
• Para Android: Instalar Android Studio

El App ID ya está en uso

Problema: Tu app ID ya está registrado.

Solución: Elige una de las alternativas sugeridas o introduce un ID de app personalizado en notación de dominio inverso.

Falta el script de build

Problema: No se encontró ningún script de build en package.json.

Solución: Añade un script de build a tu package.json:

{
  "scripts": {
    "build": "your-build-command"
  }
}

Error en la auto-inyección

Problema: CLI no puede inyectar automáticamente la integración code.

Solución: Añade code manualmente a tu archivo principal:

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

La versión de Capacitor es demasiado antigua

Problema: Tu versión de Capacitor es inferior a la v5.

Solución: Actualiza Capacitor a la v5 o superior:

• Actualización a Capacitor 5
• Actualización a Capacitor 6
• Actualización a Capacitor 7

Próximos pasos

Ahora que has completado el onboarding, explora estos temas:

Checklist de configuración inicial

Configura canales, CI y delta upload una vez para estabilidad a largo plazo

Desplegar actualizaciones

Aprende a desplegar actualizaciones desde el dashboard de Capgo

Tipos de actualización

Referencia de todos los tipos de actualización OTA: momento de aplicación, condiciones de retraso, bloqueo de versiones y entrega

Integración CI/CD

Automatiza tus despliegues de actualizaciones con CI/CD

Canales

Gestiona múltiples flujos de actualización con canales

Cifrado

Protege tus actualizaciones con cifrado de extremo a extremo

Comportamiento de actualización

Personaliza cuándo y cómo se aplican las actualizaciones (directas, delta, etc.)

Obtener ayuda

Si encuentras problemas durante el onboarding:

• Consulta la Guía de resolución de problemas
• Únete al Comunidad de Discord
• Revisa la FAQ
• Contacto Soporte

Continúa desde la guía de onboarding de CLI

Si estás usando Guía de onboarding de CLI para planificar las operaciones del dashboard y de API, conéctalo con Resumen de API para los detalles de implementación en API Overview, Introducción para los detalles de implementación en la Introducción, Claves de API para el detalle de implementación en API Keys, Dispositivos para el detalle de implementación en Devices, y Bundles para el detalle de implementación en Bundles.