Getting Started

Installation

Vous pouvez utiliser notre configuration assistée par l'IA pour installer le plug-in. Ajoutez les Capgo compétences à votre outil IA en utilisant la commande suivante :

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

Ensuite, utilisez la prompt suivante :

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 la configuration manuelle, installez le plug-in en exécutant les commandes suivantes et suivez les instructions spécifiques au 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

Pour la plupart des utilisateurs, nous recommandons de suivre le guide de démarrage rapide 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.

Vue d'ensemble

Le plugin de mise à jour Capacitor permet des mises à jour en ligne (OTA) pour vos applications Capacitor. Cela vous permet de pousser des mises à jour vers 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. Rechargement en direct: L'application passe au nouveau bundle sans nécessiter un redémarrage
4. Mode de reversion: Si une mise à jour échoue, l'application revient à la version précédente fonctionnelle

Modes d'utilisation

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

La façon la plus simple d'utiliser le plugin avec une gestion automatique de mise à 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 d'actualisation :

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

Android

Section intitulée “Android”

Section intitulée “iOS”

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 un 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 une Bundles

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

Obtenir la Bundles actuelle

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

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

Modèles d'intégration

Avec Capgo Cloud

La meilleure façon 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 de démarrage rapide principal 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é Détails complets.

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

• Appeler toujours notifyAppReady() lorsque votre application se charge avec succès
• Tester les mises à jour soigneusement avant de les envoyer en production
• Implémenter une gestion des erreurs appropriée pour les échecs de réseau
• Utiliser des numéros de version de manière cohérente
• Conserver les tailles des bundles petites pour des téléchargements plus rapides
• Surveiller 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

Continuez de Getting Started

Si vous utilisez Démarrage pour planifier le travail de plugin natif, le connecter avec En utilisant @capgo/capacitor-mise-à-jour pour la capacité native dans En utilisant @capgo/capacitor-mise-à-jour, Répertoire de Plugin Capgo pour le flux de travail du produit dans Répertoire de Plugin Capgo, Plugins Capacitor par Capgo pour le détail d'implémentation dans Plugins Capacitor par Capgo, Ajouter ou Mettre à Jour les Plugins pour le détail d'implémentation dans Ajouter ou Mettre à Jour les Plugins, et Alternatives de Plugin d'Entreprise Ionic pour le flux de travail du produit dans Alternatives de Plugin d'Entreprise Ionic.