Primeros pasos

Instalación

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Luego usa el siguiente prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-updater` plugin in my project.

Si prefieres la configuración manual, instala el plugin ejecutando estos comandos y sigue las instrucciones de cada plataforma:

npm

bun add @capgo/capacitor-updater
bunx cap sync

yarn

yarn add @capgo/capacitor-updater
bunx cap sync

pnpm

pnpm add @capgo/capacitor-updater
bunx cap sync

bun

bun add @capgo/capacitor-updater
bunx cap sync

Inicio rápido

Para la mayoría de los usuarios, recomendamos seguir la guía principal de Quickstart que cubre tanto la instalación del plugin como la integración con la nube de Capgo.

Esta guía de inicio se centra en los detalles técnicos del plugin para usuarios avanzados que quieran entender los mecanismos internos o implementar actualizaciones self-hosted.

Resumen

El plugin Capacitor Updater permite actualizaciones over-the-air (OTA) para tus aplicaciones Capacitor. Esto te permite enviar actualizaciones a tu app sin pasar por la revisión de las tiendas.

Cómo funciona

1. Descarga del bundle: El plugin descarga los bundles de actualización (archivos ZIP con tus web assets)
2. Extracción: Los bundles se extraen al almacenamiento del dispositivo
3. Hot Reload: La app cambia al nuevo bundle sin necesidad de reiniciarse
4. Fallback: Si una actualización falla, la app vuelve a la versión anterior que funcionaba

Modos de uso

1. Modo Auto-Update (recomendado)

La forma más sencilla de usar el plugin con gestión automática de actualizaciones:

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

// Plugin handles everything automatically
// Configure in capacitor.config.ts

Añade a tu capacitor.config.ts:

{
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      updateUrl: 'https://your-update-server.com/api/updates'
    }
  }
}

2. Modo manual

Para un control avanzado del proceso de actualización:

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

// Download an update
const bundle = await CapacitorUpdater.download({
  url: 'https://your-server.com/updates/v1.0.1.zip',
  version: '1.0.1'
});

// Set the bundle (will be used on next app start)
await CapacitorUpdater.set({
  id: bundle.id
});

// Or reload immediately
await CapacitorUpdater.reload();

Configuración de plataforma

iOS

No requiere configuración adicional. El plugin funciona directamente.

Android

No requiere configuración adicional. El plugin funciona directamente.

Uso básico de API

Descargar una actualización

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

const bundle = await CapacitorUpdater.download({
  url: 'https://example.com/update.zip',
  version: '1.0.1'
});

console.log('Downloaded bundle:', bundle.id);

Establecer bundle activo

// Set bundle to be used on next app start
await CapacitorUpdater.set({
  id: bundle.id
});

Recargar con el nuevo bundle

// Reload app immediately with new bundle
await CapacitorUpdater.reload();

Listar Bundles

const { bundles } = await CapacitorUpdater.list();
console.log('Available bundles:', bundles);

Eliminar un Bundle

await CapacitorUpdater.delete({
  id: 'bundle-id'
});

Obtener el Bundle actual

const { bundle } = await CapacitorUpdater.current();
console.log('Current bundle:', bundle.version);

Listeners de eventos

Escucha los eventos de actualización:

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

// Listen for download progress
CapacitorUpdater.addListener('download', (info) => {
  console.log('Download progress:', info.percent);
});

// Listen for download completion
CapacitorUpdater.addListener('downloadComplete', (bundle) => {
  console.log('Download complete:', bundle.version);
});

// Listen for update failures
CapacitorUpdater.addListener('updateFailed', (error) => {
  console.error('Update failed:', error);
});

// Listen for successful updates
CapacitorUpdater.addListener('updateAvailable', (info) => {
  console.log('Update available:', info.version);
});

Opciones de configuración

Configura el plugin en tu capacitor.config.ts:

{
  plugins: {
    CapacitorUpdater: {
      // Auto-update settings
      autoUpdate: 'atBackground',
      updateUrl: 'https://api.example.com/updates',

      // Update behavior
      resetWhenUpdate: true,

      // Version settings
      version: '1.0.0',

      // Security
      allowModifyUrl: false,

      // Stats collection
      statsUrl: 'https://api.example.com/stats',

      // Channel (for Capgo cloud)
      defaultChannel: 'production'
    }
  }
}

Patrones de integración

Con Capgo Cloud

La forma más fácil de empezar:

// Install the Capgo CLI
bun add -g @capgo/cli

// Login to Capgo
npx @capgo/cli login

// Upload your first bundle
npx @capgo/cli bundle upload

// The plugin auto-updates from Capgo cloud

Consulta la guía principal de Quickstart para más detalles.

Actualizaciones self-hosted

Aloja tu propio servidor de actualizaciones:

// Configure your update endpoint
{
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      updateUrl: 'https://your-server.com/api/check-update'
    }
  }
}

Tu servidor debe devolver:

{
  "version": "1.0.1",
  "url": "https://your-server.com/updates/1.0.1.zip"
}

Ver Modo autoalojado para más detalles.

Flujo de actualización manual

Control total sobre las actualizaciones:

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

async function checkAndUpdate() {
  // Check for updates from your server
  const response = await fetch('https://api.example.com/check-update');
  const { version, url } = await response.json();

  // Download the update
  const bundle = await CapacitorUpdater.download({
    url,
    version
  });

  // Notify bundle is ready
  await CapacitorUpdater.notifyAppReady();

  // Set as next version
  await CapacitorUpdater.set({ id: bundle.id });

  // Reload when ready
  await CapacitorUpdater.reload();
}

Buenas prácticas

• Llamar siempre a notifyAppReady() cuando tu app se carga correctamente
• Prueba las actualizaciones a fondo antes de pasarlas a producción
• Implementa un manejo de errores adecuado para fallos de red
• Usa números de versión de forma consistente
• Mantén los bundles pequeños para descargas rápidas
• Monitorea el éxito de las actualizaciones

Próximos pasos

• Referencia del plugin API - Documentación completa de API
• Configuración del plugin - Todas las opciones de configuración
• Eventos - Eventos de actualización disponibles
• Modo autoalojado - Ejecuta tu propio servidor de actualizaciones
• Desarrollo local - Prueba las actualizaciones localmente
• Depuración - Guía de resolución de problemas

Soporte

• Problemas conocidos - Problemas comunes y soluciones
• Discusiones de GitHub - Soporte de la comunidad
• Discord - Chat en tiempo real

Continúa desde Getting Started

Si estás usando Primeros pasos para planificar el trabajo con plugins nativos, conéctalo con Al usar @capgo/capacitor-updater para la funcionalidad nativa al usar @capgo/capacitor-updater, Directorio de plugins de Capgo para el flujo de trabajo del producto en Capgo Plugin Directory, Plugins de Capacitor por Capgo para el detalle de implementación en los Plugins de Capacitor por Capgo, Añadir o actualizar plugins para el detalle de implementación en Agregar o actualizar plugins, y Alternativas a plugins de Ionic Enterprise para el flujo de trabajo del producto en Alternativas a plugins de Ionic Enterprise.