Saltar al contenido

Checklist de configuración inicial

¡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”
  1. Crear canales: elige el conjunto más pequeño que encaje (ver abajo).

  2. Establecer canal de subida predeterminado en configuración de la app:

    • App individual → production
    • Equipo → development
  3. Canal de producción: public on, device self-set off, block updates under native on, auto-update guard on major.

  4. Canal de pruebas (development / staging): public off, device self-set on for QA.

  5. 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}" \
    --delta

    El --bundle valor usar ser válido versionado semántico. Valóralo en el Probador de SemVer antes de subirlo.

  6. Despliega a producción solo después de probar, desde el dashboard o CLI.

  7. 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.


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.


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, o 1.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.


--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)”
Ventana de terminal
npx @capgo/cli@latest bundle upload \
--channel development \
--bundle "1.8.0-${BUILD_NUMBER}" \
--delta

Es 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.

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}" \
--delta-only

Usa --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.


Upload to development (--delta)
→ test
→ deploy to production
→ don't touch channel settings again

ErrorSolución
Esperar OTA antes de un nuevo release en la storeRebuild y publica la app nativa tras añadir el plugin
Subir un bundle pero no desplegarlo en un channelAsignar el bundle a un channel (ej. production)
Un channel por feature, ticket o desarrolladorUsar solo release lanes permanentes
Nombres de channel dinámicos en CINombres fijos: development, production
Demasiados channels para una app sencillaEmpieza con 1-2 channels
Autoasignación de dispositivo en producciónDesactivado en producción, activado en canales de test
Omitiendo --deltaAñadir --delta para uploads; usa --delta-only solo cuando necesites ahorrar almacenamiento
Nombres de bundle sin semverSeguir versionado semántico y valida en el Probador de SemVer
Cambiar el esquema de versionado con el tiempoMantén semver; usa etiquetas pre-release para builds extra (1.8.0-20260629.1)
Metadatos / vista previa activados sin motivoDejarlo desactivado por defecto
Mensaje de «Nueva versión disponible» en una instalación nuevaOmitirlo 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.