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

Pour la plupart des utilisateurs, nous recommandons de suivre le guide de démarrage rapide principal qui couvre à la fois 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 qui souhaitent comprendre les mécanismes sous-jacents ou mettre en œuvre des mises à jour auto-hébergées.

Aperçu

Le plugin Capacitor Updater permet des mises à jour en direct (OTA) pour vos applications Capacitor. Cela vous permet de diffuser des mises à jour de votre application sans passer par les avis de l’App Store.

Comment ça marche

1. Téléchargement du bundle : le plugin télécharge les bundles de mise à jour (fichiers ZIP contenant vos ressources Web)
2. Extraction : les bundles sont extraits vers le stockage de l’appareil
3. Rechargement à chaud : l’application passe au nouveau pack sans nécessiter de redémarrage.
4. Retour : si une mise à jour échoue, l’application revient à la version de travail précédente

Modes d’utilisation

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

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

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

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

Ajoutez à votre capacitor.config.ts :

{
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      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 immédiatement.

Android

Aucune configuration supplémentaire 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 pack actif

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

Recharger avec un nouveau pack

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

Liste des lots

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

Supprimer un lot

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

Obtenir le forfait 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: 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'
    }
  }
}

Modèles d’intégration

Avec le cloud Capgo

La façon la plus simple de commencer :

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

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

Mises à jour auto-hébergées

Hébergez votre propre serveur de mise à jour :

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

Votre serveur devrait renvoyer :

{
  "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 manuelle

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 minutieusement les mises à jour avant de passer en production
• Implémenter une gestion appropriée des erreurs en cas de pannes de réseau
• Utilisez les numéros de version de manière cohérente
• Gardez les tailles de bundle petites pour des téléchargements plus rapides
• Surveiller les taux de réussite des mises à jour

Prochaines étapes- 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 - Tester les mises à jour localement
• Débogage - Guide de dépannage

Assistance

• Problèmes connus - Problèmes courants et solutions
• GitHub Discussions - Soutien de la communauté
• Discord - Chat en temps réel