Démarrage

Installation

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

Pour la plupart des utilisateurs, nous recommandons de suivre le guide de démarrage principal qui couvre à la fois l'installation du plugin et Capgo l'intégration cloud.

Ce guide de démarrage se concentre sur les détails techniques du plugin pour les utilisateurs avancés qui souhaitent comprendre les mécanismes sous-jacents ou mettre en œuvre des mises à jour auto-hébergées.

Aperçu

Le plugin de mise à jour Capacitor permet des mises à jour hors ligne (OTA) pour vos applications Capacitor. Cela vous permet de pousser des mises à jour à votre application sans passer par les examens des magasins d'applications.

Comment ça marche

1. Téléchargement du paquet : Le plugin télécharge les paquets de mise à jour (fichiers ZIP contenant vos actifs web)
2. Extraction : Les paquets sont extraits sur le stockage du dispositif
3. Reloading chaud : L'application passe au nouveau paquet sans nécessiter un redémarrage
4. Redondance: Si une mise à jour échoue, l'application revient à la version fonctionnelle précédente

Modes d'utilisation

1. Mode de mise à jour automatique (Recommandé)

La méthode la plus simple pour 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ôle 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 de la plateforme

iOS

Aucune configuration supplémentaire requise. Le plugin fonctionne directement.

Android

Aucune configuration supplémentaire requise. Le plugin fonctionne directement.

Utilisation de base 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'
});

Obtenir le Bundle actuel

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

Écouteurs d'événements

Écouter 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

Configurer 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'
    }
  }
}

Modèles d'intégration

Avec Capgo Cloud

La manière la 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

Voir le guide de démarrage rapide principal pour plus de détails.

Mises à jour auto-hébergées

Héberger votre propre serveur de mise à jour :

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

Votre serveur doit retourner :

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

Voir Mode Auto-Hébergé pour plus de 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();
}

Meilleures Pratiques

• Appelez toujours notifyAppReady() lorsque votre application se charge avec succès
• Testez les mises à jour soigneusement avant de les envoyer en production
• Implémentez un traitement d'erreur approprié pour les échecs de réseau
• Utilisez des numéros de version de manière cohérente
• Conservez les tailles des paquets petites pour des téléchargements plus rapides
• Surveillez les taux de réussite des mises à jour

Étapes suivantes

• Référence du plugin API - Documentation complète de 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 courants et solutions
• GitHub Discussions - Support communautaire
• Discord - Chat en temps réel