Checklist de configuración inicial
Copia un prompt de configuración con los pasos de instalación y la guía completa en markdown para este plugin.
¡Ya terminaste! onboarding. Ahora configura Capgo una vez. Después de eso, el trabajo diario es solo subir → probar → desplegar.
Regla: los canales son vías de publicación (development, production), no tickets, funciones ni nombres de desarrolladores.
Checklist de configuración inicial
Section titled “One time setup checklist”-
Crear canales: elige el conjunto más pequeño que encaje (ver abajo).
-
Establecer canal de subida predeterminado en configuración de la app:
- App individual →
production - Equipo →
development
- App individual →
-
Canal de producción: public on, device self-set off, block updates under native on, auto-update guard on
major. -
Canal de pruebas (
development/staging): public off, device self-set on for QA. -
Sube desde tu CI con
--delta(checksum y dependencias nativas son automáticos):Ventana de terminal npx @capgo/cli@latest bundle upload \--channel development \--bundle "1.8.0-${BUILD_NUMBER}" \--comment "commit ${GIT_SHA:0:7} run ${CI_RUN_ID}" \--deltaEl
--bundlevalor usar ser válido versionado semántico. Valóralo en el Probador de SemVer antes de subirlo. -
Despliega a producción solo después de probar, desde el dashboard o CLI.
-
Equipo y seguridad: invita una vez, con los permisos mínimos, 2FA para la organización, una clave API en CI.
Deja la cifración, min_update_version, los metadatos y la vista previa off a menos que tengas una razón clara.
Elige tu tamaño
Sección titulada «Elige tu tamaño»Sencillo: 1 app, 1 canal: production
Equipo: development + production. Sube a dev, despliega a prod.
Versiones nativas: añade canales solo cuando sea necesario, p. ej. production-9.0 + test-9.0. Mantén a los usuarios de la tienda en el canal principal de producción.
Muchas apps: mismo modelo simple por app (normalmente uno production cada una). No crees canales extra solo porque la organización sea grande.
Tren de releases (opcional): staging → rc → production. Misma plantilla en cada app que la necesite.
Nombre del bundle vs comentario
Sección titulada “Nombre del bundle vs comentario”Los nombres de bundle deben obligatorias seguir versionado semántico. Capgo usa semver para comprobaciones de compatibilidad, reglas de actualización automática de canales y rollbacks. Valida cada nombre en el Probador de SemVer antes de subirlo.
- Nombre = semver desde CI, p. ej.
1.8.0,1.8.0-beta.1, o1.8.0-20260629.42 - Comentario = texto libre para humanos →
commit abc1234 run 28059070270
Usar semver pre-lanzamiento etiquetas (la parte después de -) cuando publicas muchos builds con el mismo MAJOR.MINOR.PATCH. Por ejemplo, mantén 1.8.0 y añade la fecha o el contador de build en el pre-release: 1.8.0-20260629.1, 1.8.0-beta.2. No inventes formatos personalizados como fix-login-bug o 2.5.2026062306. No son semver válidos y las subidas fallarán o se comportarán de forma impredecible.
Pon las release notes en --comment, no en el nombre del bundle.
Ver también segmentación por versión y versionado de bundles.
Subida delta
Sección titulada “Subida delta”--delta subidas archivos delta para que los dispositivos descarguen solo los archivos modificados en lugar del bundle completo cada vez. El checksum siempre se calcula automáticamente. No pasas ningún flag de checksum.
Por defecto: --delta (archivos delta + copia de seguridad zip)
Sección titulada “Predeterminado: --delta (archivos delta + copia de seguridad zip)”npx @capgo/cli@latest bundle upload \ --channel development \ --bundle "1.8.0-${BUILD_NUMBER}" \ --deltaEs el valor predeterminado recomendado para la mayoría de las apps. Capgo almacena los archivos delta y y mantiene el zip completo como copia de seguridad. Los dispositivos con una versión antigua del plugin sin soporte para Delta usan el zip. Ideal cuando el costo de almacenamiento no es tu principal preocupación.
Ahorro de almacenamiento: --delta-only
Sección titulada “Ahorro de almacenamiento: --delta-only”npx @capgo/cli@latest bundle upload \ --channel development \ --bundle "1.8.0-${BUILD_NUMBER}" \ --comment "commit ${GIT_SHA:0:7} run ${CI_RUN_ID}" \ --delta-onlyUsa --delta-only cuando quieres reducir el almacenamiento de Capgo. Solo se almacenan los archivos delta, no el zip completo. Elige esta opción para apps grandes o con alto volumen de subidas, donde el almacenamiento se acumula.
Trade-off: sin la copia de seguridad zip en el servidor, dependes totalmente de los archivos delta, y los dispositivos con una versión antigua del plugin sin soporte Delta no pueden actualizarse. Omitir --delta-only a menos que realmente necesites el ahorro de almacenamiento.
No se requiere configuración adicional del plugin en el dispositivo. El updater lee la lista de archivos delta y solo descarga los archivos modificados.
Flujo de trabajo diario
Sección titulada “Flujo de trabajo diario”Upload to development (--delta) → test → deploy to production → don't touch channel settings againErrores comunes
Sección titulada “Errores comunes”| Error | Solución |
|---|---|
| Esperar OTA antes de un nuevo release en la store | Rebuild y publica la app nativa tras añadir el plugin |
| Subir un bundle pero no desplegarlo en un channel | Asignar el bundle a un channel (ej. production) |
| Un channel por feature, ticket o desarrollador | Usar solo release lanes permanentes |
| Nombres de channel dinámicos en CI | Nombres fijos: development, production |
| Demasiados channels para una app sencilla | Empieza con 1-2 channels |
| Autoasignación de dispositivo en producción | Desactivado en producción, activado en canales de test |
Omitiendo --delta | Añadir --delta para uploads; usa --delta-only solo cuando necesites ahorrar almacenamiento |
| Nombres de bundle sin semver | Seguir versionado semántico y valida en el Probador de SemVer |
| Cambiar el esquema de versionado con el tiempo | Mantén semver; usa etiquetas pre-release para builds extra (1.8.0-20260629.1) |
| Metadatos / vista previa activados sin motivo | Dejarlo desactivado por defecto |
| Mensaje de «Nueva versión disponible» en una instalación nueva | Omitirlo cuando current() devuelve bundle.id === "builtin" (ver abajo) |
Revisión de App Store: sin mensaje de actualización en una instalación nueva
Sección titulada «Revisión de App Store: sin mensaje de actualización en una instalación nueva»Apple acepta apps que usan Capgo. Los revisores rechazan la interfaz que lo rodea: un mensaje de “nueva versión disponible” o “actualizando” mostrado en el primer arranque.
Esto afecta principalmente a configuraciones autoalojadas y manuales, donde tu app realiza su propia verificación de versión y muestra su propio prompt.
El revisor instala tu binario de la tienda. Es más antiguo que tu último bundle, por lo que la primera verificación encuentra un bundle de inmediato: tu llamada al servidor lo devuelve, o el updater lo encuentra y emite updateAvailable. Si tu app muestra un mensaje en ese momento, el revisor lo verá.
Justo después de una instalación nueva o una actualización nativa de la tienda, la app ejecuta el bundle incluido y current() devuelve bundle.id === "builtin". Omite tu mensaje en ese caso:
import { CapacitorUpdater } from '@capgo/capacitor-updater'
const { bundle } = await CapacitorUpdater.current()if (bundle.id !== 'builtin') { showNewVersionMessage()}En cualquier interfaz visible, evita las palabras “update”, “live update”, “OTA”, “downloading” e “installing”. Consulta cumplimiento.