Getting Started

Instalación

Puedes utilizar nuestra configuración asistida por IA para instalar el plugin. Agrega las Capgo habilidades a tu herramienta de IA utilizando el siguiente comando:

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

Luego utilice la siguiente solicitud:

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

Si prefiere la configuración manual, instale el complemento ejecutando los siguientes comandos y siguiendo las instrucciones específicas de la plataforma a continuación:

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 el guía de inicio rápido principal que cubre tanto la instalación del complemento como Capgo la integración en la nube.

Esta guía de inicio se centra en los detalles técnicos del complemento para usuarios avanzados que desean comprender los mecanismos subyacentes o implementar actualizaciones autoadministradas.

Resumen

The Capacitor Actualizador de plugin permite actualizaciones por aire (OTA) para sus aplicaciones Capacitor. Esto le permite enviar actualizaciones a su aplicación sin pasar por revisiones de tiendas de aplicaciones.

¿Cómo Funciona

1. Descarga de paquete: El plugin descarga paquetes de actualización (archivos ZIP que contienen sus activos web)
2. Extracción: Los paquetes se extraen al almacenamiento del dispositivo
3. Recarga Caliente: La aplicación se cambia a el nuevo paquete sin requerir reiniciar
4. Fall back: Si una actualización falla, la aplicación vuelve a la versión anterior que funcionaba

Modos de Uso

1. Modo de actualización automática (Recomendado)

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

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

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

Agregar 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 se requiere configuración adicional. El plugin funciona de forma predeterminada.

Android

No se requiere configuración adicional. El plugin funciona de forma predeterminada.

Uso básico 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 Paquete Activo

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

Recargar con Nuevo Paquete

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

Lista de Paquetes

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

Eliminar un Paquete

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

Obtener Paquete Actual

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

Escuchadores de Eventos

Escuchar 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 complemento 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

Ver el guía rápida principal para detalles.

Actualizaciones Autoalojadas

Alquila tu propio servidor de actualizaciones:

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

Su servidor debería devolver:

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

Ver Modo autoalojado Para obtener detalles completos.

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();
}

Prácticas recomendadas

• Siempre llamar notifyAppReady() cuando su aplicación se carga correctamente
• Pruebe actualizaciones exhaustivamente antes de enviarlas a producción
• Implemente un manejo de errores adecuado para fallos de red
• Utilice números de versión de manera consistente
• Mantenga los tamaños de paquetes pequeños para descargas más rápidas
• Monitorear las tasas de éxito de actualizaciones

Pasos siguientes

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

Soporte

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

Seguir adelante desde Getting Started

Si estás utilizando Getting Started para planificar el trabajo de plugin nativo, conectarlo con Usando @capgo/capacitor-actualizador para la capacidad nativa en Usando @capgo/capacitor-actualizador, Capgo Directorio de Plugin para el flujo de trabajo del producto en el directorio de plugins Capgo Capacitor Plugins por Capgo para el detalle de implementación en Capacitor Plugins por Capgo, Agregar o Actualizar Plugins para el detalle de implementación en Agregar o Actualizar Plugins, y Alternativas de Plugins de Ionic Enterprise para el flujo de trabajo del producto en Alternativas de Plugins de Ionic Enterprise.