Guía de Onboarding de CLI

Vista rápida

La Capgo CLI proporciona una onboarding interactiva que configura actualizaciones en vivo para tu Capacitor aplicación. Tendrás:

1. ✅ Registra tu aplicación en Capgo
2. 🔌 Instala y configura el plugin de actualizador
3. 🚀 Despliegue su primer live update
4. Prueba la actualización en tu dispositivo

Tiempo estimado: 10-20 minutos (varía según su velocidad de internet y tiempo de compilación)

Consejo

The onboarding is fully resumable - exit anytime and continue later from where you left off.

Inicio del proceso de incorporación

Ejecutar la orden de incorporación con su clave API:

npx @capgo/cli@latest init [APIKEY]

Verá el mensaje de bienvenida:

Capgo onboarding 🛫

¿Qué sucede durante la incorporación?

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

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

• Verifique su entorno de desarrollo (Xcode/Android Studio)
• Agregue su aplicación a Capgo y cree un canal de producción
• Instale el @capgo/capacitor-updater plugin
• Inyecte los code necesarios en su aplicación
• Optionally enable end-to-end encryption
• Elige una plataforma para la prueba (iOS o Android)

Etapa de prueba (Pasos 7-12):

• Build your app and run it on a device/simulator
• Haz un cambio visible code (automático o manual)
• Sube el paquete actualizado a Capgo
• Ve el live update aparecer en tu dispositivo en tiempo real

Compleción (Paso 13):

• Your app is ready for live updates! 🎉

El proceso de incorporación de 13 pasos

Paso 1: Verifica los requisitos previos

La CLI verifica tu entorno de desarrollo para asegurarse de que tengas las herramientas necesarias instaladas.

¿Qué se verifica:

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

Posibles resultados:

✅ Se encontraron ambos entornos:

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

⚠️ No se encontró ningún entorno:

⚠️ 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ías ser preguntado:

Cuidado

Si no se detecta un entorno de desarrollo, se le preguntará si desea continuar. Se recomienda instalar al menos una plataforma antes de proceder.

Paso 2: Agrega tu aplicación

La CLI se encargará de iniciar sesión en Capgo y agregar tu aplicación a tu cuenta.

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

❓ Add {appId} in Capgo?

Si tu ID de aplicación ya está tomado:

La 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?

You can choose a suggestion or enter a custom app ID.

Nota

App IDs deben seguir la notación de dominio inverso (por ejemplo, com.example.myapp)

Crear Canal de Producción: paso 3

Canales te permiten gestionar diferentes flujos de actualizaciones para tu aplicación.

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

Consejo

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

If seleccionas Sí:

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

Un canal de producción será creado y establecido como predeterminado. Esta es la opción recomendada para la mayoría de los usuarios.

If seleccionas No:

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

Necesitarás crear y configurar canales manualmente más tarde. Alternativamente, puedes:

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

Step 4: Instalar Plugin de Actualizador

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 5Instala @capgo/capacitor-updater v5
• Capacitor 6Instala @capgo/capacitor-updater Instala
• Capacitor 7: Instala @capgo/capacitor-updater v7
• Capacitor 8+: Instala la versión más reciente

Cuidado

Capgo solo admite Capacitor v5 y superior. Si estás utilizando una versión anterior, necesitarás actualizar primero.

Opción de actualizaciones instantáneas:

Después de la instalación, te preguntarán:

❓ 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? With instant updates enabled, your app applies updates immediately when backgrounded and reopened. This works seamlessly because Capgo can distribute updates worldwide in under 300ms. Without it (standard mode), updates download in the background and apply on the next app restart. Instant updates are great for faster iteration during development and critical bug fixes in production.

Si selecciona Sí:

• Updates will be configured to apply immediately when the app is backgrounded and reopened
• autoUpdate: 'always' y autoSplashscreen: true se agregarán a su configuración
• @capacitor/splash-screen se instalarán si faltan, con launchAutoHide: false
• Su capacitor.config.ts se actualizarán automáticamente
• Actualizaciones delta manténganse habilitadas. Aplicar instantáneamente (always, atInstall, onLaunchdebería seguir utilizando npx @capgo/cli@latest bundle upload --delta so only changed files download and the user is not left waiting on a full zip

Si selecciona No:

• Updates will use standard behavior (download in background, apply on next restart)
• Siempre puede habilitar actualizaciones instantáneas más tarde modificando su capacitor.config.ts

Paso 5: Agregar Integración Code

El CLI inyectará automáticamente los code requeridos en su archivo de aplicación principal.

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

¿Qué se agrega:

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

CapacitorUpdater.notifyAppReady()

Deteción de tipo de proyecto:

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

Consejo

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

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

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

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

Para otros frameworks: Add to your main entry file (e.g., main.ts, index.js, App.tsx):

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

CapacitorUpdater.notifyAppReady()

Place this code after your imports and before your app initialization. For more details, see the Guía para agregar una aplicación .

Paso 6: Configuración de cifrado (opcional)

End-to-end encryption adds an extra security layer for your updates.

🔐 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

Encryption is only available for Capacitor v6 and above.

Si habilitas el cifrado, el CLI realizará:

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

Step 7: Seleccionar Plataforma

Elige qué plataforma probar durante el proceso de incorporación.

📱 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 el proceso de incorporación. Tu aplicación final apoyará todas las plataformas.

Step 8: Construye tu proyecto

El CLI construirá tu aplicación 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 compilación
3. Ejecuta npx cap sync {platform}

Si falta el script de compilación:

Se te pedirá si deseas saltarte la compilación o agregar un script de compilación a tu package.json.

Paso 9: Ejecutar en dispositivo

Prueba la versión inicial de tu aplicación 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: Hacer un cambio de prueba

Es hora 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: El CLI modificará automáticamente tus archivos para agregar una bandera de prueba visible o cambiar.

Modo manual: Tú haces tus propios cambios (por ejemplo, cambiar texto, colores o agregar 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

Construir con cambios:

❓ Build {appId} with changes before uploading?

Consejo

Si necesitas construir manualmente en otra terminal, selecciona “No” y construye tú mismo, luego continúa.

Paso 11: Subir paquete

Sube tu paquete de aplicación actualizado a Capgo.

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

La CLI ejecuta:

npx @capgo/cli@latest bundle upload

Consejo

Delta updates with instant updates: Si habilitaste actualizaciones instantáneas en el paso 4, el CLI solicitará automáticamente si deseas habilitar actualizaciones delta. Las actualizaciones delta envían solo los archivos que cambiaron entre versiones en lugar de todo el paquete. Dado que normalmente solo cambian unos pocos archivos entre actualizaciones, esto hace que las descargas sean mucho más rápidas. Selecciona Sí for the best experience with instant updates.

para obtener la mejor experiencia con actualizaciones instantáneas.

💡 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)

Caution

For monorepos, you may need to provide additional paths to your package.json and node_modules.

y

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

Paso 12: Prueba 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

Monitorear registros:

❓ Monitor Capgo logs to verify the update worked?

Si seleccionas ¡Sí, verás registros en vivo de tu dispositivo que muestran el proceso de actualización.

Paso 13: Finalización

Welcome onboard ✈️!

Felicidades! Has configurado con éxito las actualizaciones en vivo de Capgo para tu aplicación.

Lo que has logrado

After completing the onboarding, you have:

✅ Aplicación Registrada

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

✅ Plugin Instalado

El plugin de actualización Capacitor está instalado y configurado

✅ Code Integrado

La integración code se agrega a tu aplicación

✅ Actualización probada

Has desplegado con éxito y recibido un live update

Flujo diario

Para actualizaciones posteriores, utilice:

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

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

Reanudando la configuración inicial

Puedes reanudar el proceso de inicio en cualquier momento.

npx @capgo/cli@latest init [APIKEY]

Verá:

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

Consejo

Progress is saved locally, so you can safely exit and resume the onboarding process.

Troubleshooting

No Entorno de Desarrollo

Problema: Ni Xcode ni Android SDK se detecta.

Solución:

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

ID de la aplicación ya tomado

Problema: Su ID de aplicación ya está registrado.

Solución: Elige una de las sugerencias alternativas o ingresa un ID de aplicación personalizado en notación de dominio inverso.

Script de compilación faltante

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

Solución: Agrega un script de compilación a tu package.json:

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

Falló la inyección automática

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

Solución: Agregue code manualmente a su archivo principal:

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

CapacitorUpdater.notifyAppReady()

Capacitor Versión demasiado antigua

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

Solución: Actualice Capacitor a v5 o superior:

• Actualizando a Capacitor 5
• Actualizando a Capacitor 6
• Actualizando a Capacitor 7

Pasos siguientes

Ahora que has completado la configuración de inicio, explora estos temas:

Lista de verificación de configuración única

Configure canales, CI y subida de delta una vez para estabilidad a largo plazo

Despliegue de actualizaciones

Aprende a desplegar actualizaciones desde la consola de Capgo

Tipos de Actualización

Referencia de todos los tipos de actualizaciones OTA: aplicar plazos, condiciones de retraso, bloqueo de versión y entrega.

Integración CI/CD

Automatice sus despliegues de actualizaciones con CI/CD

Canales

Gestione múltiples flujos de actualizaciones con canales

Cifrado

Secure your updates with end-to-end encryption

Comportamiento de Actualización

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

Obtener Ayuda

Si encuentra problemas durante la configuración:

• Verifique el Guía de solución de problemas
• Únete a la Comunidad de Discord
• Revisa el FAQ
• Contacto Soporte

Sigue adelante desde CLI Guía de Onboarding

Si está utilizando CLI Guía de Inicio de Sesión para planificar la consola y las API operaciones, conecte con API Visión General para los detalles de implementación en API Visión General, Introducción para los detalles de implementación en Introducción, API Claves para los detalles de implementación en API Claves, Dispositivos para los detalles de implementación en Dispositivos, y Paquetes para los detalles de implementación en Paquetes.