Prise en main

Installation

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

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

Utilisez ensuite le prompt suivant :

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

Si vous préférez une installation manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à chaque plateforme ci-dessous :

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

Démarrage rapide

For most users, we recommend following the guide de démarrage rapide principal qui couvre l'installation du plugin et l'intégration cloud de Capgo.

Ce guide de démarrage se concentre sur les détails techniques du plugin pour les utilisateurs avancés souhaitant comprendre les mécanismes sous-jacents ou implémenter des mises à jour auto-hébergées.

Aperçu

Le plugin Capacitor Updater permet d'effectuer des mises à jour over-the-air (OTA) pour vos applications Capacitor. Cela vous permet de déployer des mises à jour sans passer par la revue des stores.

Comment ça marche

1. Téléchargement du bundle: Le plugin télécharge les bundles de mise à jour (fichiers ZIP contenant vos assets web)
2. Extraction: Les bundles sont extraits sur le stockage de l'appareil
3. Hot Reload: L'application bascule sur le nouveau bundle sans nécessiter de redémarrage
4. Fallback: Si une mise à jour échoue, l'app revient à la version précédente fonctionnelle

Modes d'utilisation

1. Mode auto-update (recommandé)

La manière la plus simple d'utiliser le plugin avec une gestion automatique des mises à jour :

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

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

Ajouter à votre capacitor.config.ts:

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

2. Mode manuel

Pour un contrôl’avancé du processus de mise à jour :

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

Configuration des plateformes

iOS

Aucune configuration supplémentaire n'est requise. Le plugin fonctionne immédiatement.

Android

Aucune configuration supplémentaire n'est requise. Le plugin fonctionne immédiatement.

Utilisation de base de API

Télécharger une 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);

Définir le bundle actif

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

Recharger avec le nouveau bundle

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

Lister les bundles

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

Supprimer un bundle

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

Récupérer le bundle actuel

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

Écouteurs d'événements

Écoutez les événements de mise à jour :

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

Options de configuration

Configurez le plugin dans votre 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'
    }
  }
}

Patterns d'intégration

Avec Capgo Cloud

Le moyen le plus simple de commencer :

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

Consultez le guide Quickstart principal pour plus de détails.

Mises à jour auto-hébergées

Hébergez votre propre serveur de mises à jour :

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

Votre serveur doit renvoyer :

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

Consultez Mode auto-hébergé pour tous les détails.

Flux de mise à jour manuel

Contrôle total sur les 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();
}

Bonnes pratiques

• Appelez toujours notifyAppReady() lorsque votre application se charge avec succès
• Testez minutieusement les mises à jour avant la production
• Implémentez une gestion d'erreurs adaptée aux pannes réseau
• Utilisez les numéros de version de manière cohérente
• Gardez des bundles légers pour des téléchargements plus rapides
• Surveillez le taux de réussite des mises à jour

Étapes suivantes

• Référence du plugin API - Consultez la documentation API
• Paramètres du plugin - Toutes les options de configuration
• Événements - Événements de mise à jour disponibles
• Mode auto-hébergé - Exécutez votre propre serveur de mise à jour
• Développement local - Testez les mises à jour localement
• Débogage - Guide de dépannage

Support

• Problèmes connus - Problèmes et solutions courants
• Discussions GitHub - Support communautaire
• Discord - Chat en temps réel

Continuer depuis Getting Started

Si vous utilisez Prise en main pour planifier le travail sur les plugins natifs, connectez-l’à Utiliser @capgo/capacitor-updater pour la capacité native dans « Utiliser @capgo/capacitor-updater », Capgo Répertoire des plugins pour le workflow produit dans Capgo Plugin Directory, Plugins Capacitor par Capgo pour les détails d'implémentation dans Plugins Capacitor par Capgo, Ajouter ou mettre à jour des plugins pour les détails d'implémentation dans Ajout ou mise à jour de plugins, et Alternatives aux plugins Ionic Enterprise pour le workflow produit dans Alternatives aux plugins Ionic Enterprise.