Commencer

Installation

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

Démarrage rapide

For most Utilisateurs, we recommend following the [main Démarrage rapide Guide](/docs/getting-started/Démarrage rapide/) which covers both the plugin Installation and Capgo cloud integration.

This getting-started Guide focuses on the technical plugin details for advanced Utilisateurs who want to understand the underlying mechanisms or implement self-hosted Mises à jour.

Aperçu

The Capacitor Updater plugin enables over-the-air (OTA) Mises à jour for your Capacitor applications. This allows you to Pousser Mises à jour to your Application without going through Application Store reviews.

How It Works

1. Bundle Télécharger: The plugin downloads Mise à jour Bundles (ZIP files containing your web assets)
2. Extraction: Bundles are extracted to the Appareil’s storage
3. Hot Reload: The Application switches to the Nouveau Bundle without requiring a Redémarrer
4. Fallback: If an Mise à jour fails, the Application reverts to the Précédent working Version

Utilisation Modes

1. Auto-Mise à jour Mode (Recommended)

The simplest way to use the plugin with automatic Mise à jour management:

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

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

Add to your capacitor.config.ts:

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

2. Manual Mode

For advanced control over the Mise à jour process:

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

Platform Configuration

iOS

No additional Configuration required. The plugin works out of the box.

Android

No additional Configuration required. The plugin works out of the box.

Basic API Utilisation

Télécharger an Mise à jour

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

Set Actif Bundle

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

Reload with Nouveau Bundle

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

List Bundles

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

Supprimer a Bundle

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

Get Current Bundle

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

Event Listeners

Listen for Mise à jour events:

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

Configuration Options

Configure the plugin in your capacitor.config.ts:

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

      // Update behavior
      resetWhenUpdate: true,
      directUpdate: false,

      // Version settings
      version: '1.0.0',

      // Security
      allowModifyUrl: false,

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

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

Integration Patterns

With Capgo Cloud

The easiest way to get started:

// Install the Capgo CLI
npm install -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

See the [main Démarrage rapide Guide](/docs/getting-started/Démarrage rapide/) for details.

Self-Hosted Mises à jour

Host your own Mise à jour server:

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

Your server should return:

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

See Self-Hosted Mode for Terminé details.

Manual Mise à jour Flow

Terminé control over Mises à jour:

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

Best Practices

• Always call notifyAppReady() when your app successfully loads
• Test Mises à jour thoroughly before pushing to Production
• Implement proper Erreur handling for network failures
• Use Version numbers consistently
• Keep Bundle sizes small for faster downloads
• Monitor Mise à jour Succès rates

Suivant Steps

• Plugin API Référence - Terminé API Documentation
• Plugin Paramètres - All Configuration Options
• Events - Disponible Mise à jour events
• Self-Hosted Mode - Run your own Mise à jour server
• Local Développement - Test Mises à jour locally
• Débogage - Dépannage Guide

Support

• Problèmes connus - Common problems and Solutions
• GitHub Discussions - Communauté Support
• Discord - Real-time chat