Primeros Pasos

Instalación

npm

npm install @capgo/capacitor-updater
npx cap sync

yarn

yarn add @capgo/capacitor-updater
npx cap sync

pnpm

pnpm add @capgo/capacitor-updater
npx cap sync

bun

bun add @capgo/capacitor-updater
npx cap sync

Inicio Rápido

Para la mayoría de 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 primeros pasos se enfoca en los detalles técnicos del Plugin para usuarios avanzados que quieren entender los mecanismos subyacentes o implementar actualizaciones auto-hospedadas.

Descripción General

El Plugin Capacitor Updater habilita actualizaciones over-the-air (OTA) para tus aplicaciones Capacitor. Esto te permite enviar actualizaciones a tu aplicación sin pasar por las revisiones de tiendas de aplicaciones.

Cómo Funciona

1. Descarga de Paquete: El Plugin descarga Paquetes de actualización (archivos ZIP que contienen tus assets web)
2. Extracción: Los Paquetes se extraen al almacenamiento del dispositivo
3. Hot Reload: La aplicación cambia al nuevo Paquete sin requerir un reinicio
4. Fallback: Si una actualización falla, la aplicación revierte a la versión de trabajo anterior

Modos de Uso

1. Modo de Actualización Automática (Recomendado)

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

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

// El plugin maneja todo automáticamente
// Configura en capacitor.config.ts

Agrega a tu capacitor.config.ts:

{
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      updateUrl: 'https://tu-servidor-actualizaciones.com/api/updates'
    }
  }
}

2. Modo Manual

Para control avanzado sobre el proceso de actualización:

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

// Descargar una actualización
const bundle = await CapacitorUpdater.download({
  url: 'https://tu-servidor.com/updates/v1.0.1.zip',
  version: '1.0.1'
});

// Establecer el bundle (se usará en el próximo inicio de la aplicación)
await CapacitorUpdater.set({
  id: bundle.id
});

// O recargar inmediatamente
await CapacitorUpdater.reload();

Configuración de Plataforma

iOS

No se requiere configuración adicional. El Plugin funciona out of El box.

Android

No se requiere configuración adicional. El Plugin funciona out of El box.

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('Bundle descargado:', bundle.id);

Establecer Paquete Activo

// Establecer bundle para usar en el próximo inicio de la aplicación
await CapacitorUpdater.set({
  id: bundle.id
});

Recargar con Nuevo Paquete

// Recargar aplicación inmediatamente con nuevo bundle
await CapacitorUpdater.reload();

Listar Paquetes

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

Eliminar un Paquete

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

Obtener Paquete Actual

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

Listeners de Eventos

Escucha eventos de actualización:

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

// Escuchar progreso de descarga
CapacitorUpdater.addListener('download', (info) => {
  console.log('Progreso de descarga:', info.percent);
});

// Escuchar finalización de descarga
CapacitorUpdater.addListener('downloadComplete', (bundle) => {
  console.log('Descarga completa:', bundle.version);
});

// Escuchar fallos de actualización
CapacitorUpdater.addListener('updateFailed', (error) => {
  console.error('Actualización fallida:', error);
});

// Escuchar actualizaciones exitosas
CapacitorUpdater.addListener('updateAvailable', (info) => {
  console.log('Actualización disponible:', info.version);
});

Opciones de Configuración

Configura el Plugin en tu capacitor.config.ts:

{
  plugins: {
    CapacitorUpdater: {
      // Configuraciones de actualización automática
      autoUpdate: true,
      updateUrl: 'https://api.example.com/updates',

      // Comportamiento de actualización
      resetWhenUpdate: true,
      directUpdate: false,

      // Configuraciones de versión
      version: '1.0.0',

      // Seguridad
      allowModifyUrl: false,

      // Recopilación de estadísticas
      statsUrl: 'https://api.example.com/stats',

      // Canal (para nube de Capgo)
      defaultChannel: 'production'
    }
  }
}

Patrones de Integración

Con Nube de Capgo

La forma más fácil de comenzar:

// Instalar el CLI de Capgo
npm install -g @capgo/cli

// Iniciar sesión en Capgo
npx @capgo/cli login

// Subir tu primer bundle
npx @capgo/cli bundle upload

// El plugin se actualiza automáticamente desde la nube de Capgo

Consulta la guía principal de Quickstart para detalles.

Actualizaciones Auto-hospedadas

Hospeda tu propio servidor de actualizaciones:

// Configura tu endpoint de actualización
{
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      updateUrl: 'https://tu-servidor.com/api/check-update'
    }
  }
}

Tu servidor debe retornar:

{
  "version": "1.0.1",
  "url": "https://tu-servidor.com/updates/1.0.1.zip"
}

Consulta Modo Auto-hospedado para detalles completos.

Flujo de Actualización Manual

Control completo sobre las actualizaciones:

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

async function checkAndUpdate() {
  // Verificar actualizaciones desde tu servidor
  const response = await fetch('https://api.example.com/check-update');
  const { version, url } = await response.json();

  // Descargar la actualización
  const bundle = await CapacitorUpdater.download({
    url,
    version
  });

  // Notificar que el bundle está listo
  await CapacitorUpdater.notifyAppReady();

  // Establecer como próxima versión
  await CapacitorUpdater.set({ id: bundle.id });

  // Recargar cuando esté listo
  await CapacitorUpdater.reload();
}

Mejores Prácticas

• Siempre llama a notifyAppReady() cuando tu aplicación se carga exitosamente
• Prueba las actualizaciones a fondo antes de enviarlas a producción
• Implementa manejo apropiado de errores para fallos de red
• Usa números de versión de manera consistente
• Mantén los tamaños de Paquete pequeños para descargas más rápidas
• Monitorea las tasas de éxito de actualizaciones

Próximos Pasos

• Referencia de API del Plugin - Documentación completa de API
• Configuración del Plugin - Todas las opciones de configuración
• Eventos - Eventos de actualización disponibles
• Modo Auto-hospedado - Ejecuta tu propio servidor de actualizaciones
• Desarrollo Local - Prueba actualizaciones localmente
• Depuración - Guía de solución de problemas

Soporte

• Problemas Conocidos - Problemas comunes y soluciones
• Discusiones de GitHub - Soporte comunitario
• Discord - Chat en tiempo real