Getting Started

Installation

Sie können unsere AI-gestützte Einrichtung verwenden, um das Plugin zu installieren. Fügen Sie den Capgo-Fähigkeiten Ihrer AI-Werkzeug mit der folgenden Befehl hinzu:

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

Verwenden Sie dann den folgenden Prompt:

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

Wenn Sie die manuelle Einrichtung bevorzugen, installieren Sie das Plugin, indem Sie die folgenden Befehle ausführen und folgen Sie den unten angegebenen Plattform-spezifischen Anweisungen:

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

Schnellstart

Für die meisten Benutzer empfehlen wir, sich an die Hauptanleitung für den Schnellstart welche sowohl die Plugin-Installation als auch Capgo die Cloud-Integration abdeckt.

Diese Anleitung zum Einstieg konzentriert sich auf die technischen Plugin-Details für fortgeschrittene Benutzer, die die zugrunde liegenden Mechanismen verstehen möchten oder selbst gehostete Updates implementieren möchten.

Übersicht

Das Capacitor Updater-Plugin ermöglicht über die Luft (OTA) Updates für Ihre Capacitor Anwendungen. Dies ermöglicht es Ihnen, Updates an Ihre App zu pushen, ohne durch App-Store-Überprüfungen gehen zu müssen.

Wie es funktioniert

1. Bundle-Download: Das Plugin lädt Update-Bundles (ZIP-Dateien, die Ihre Web-Assets enthalten) herunter
2. Extraktion: Bundles werden auf dem Gerätespeicher extrahiert
3. Hot Reload: Die App wechselt zum neuen Bundle, ohne dass ein Neustart erforderlich ist
4. Fallback: Wenn ein Update fehlschlägt, kehrt die App zur vorherigen funktionierenden Version zurück

Usage Modes

1. Automatischer Update-Modus (Empfohlen)

Der einfachste Weg, den Plugin mit automatischer Update-Verwaltung zu verwenden:

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

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

Fügen Sie Ihrem capacitor.config.ts:

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

2. Manueller Modus

Für eine fortgeschrittene Kontrolle über den Updateprozess:

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

Plattform-Konfiguration

iOS

Keine zusätzliche Konfiguration erforderlich. Der Plugin funktioniert direkt aus der Box.

Android

Keine zusätzliche Konfiguration erforderlich. Der Plugin funktioniert direkt aus der Box.

Grundlegende API Verwendung

Ein Update herunterladen

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

Aktives Bundle setzen

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

Mit neuem Bundle neu laden

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

Bundles auflisten

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

Paket löschen

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

aktuelles Paket abrufen

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

Event-Listener

Für Aktualisierungsereignisse abonnieren:

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

Konfigurationsoptionen

Konfigurieren Sie das Plugin in Ihrem 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'
    }
  }
}

Integrationsschemata

Mit Capgo Cloud

Der einfachste Weg, loszulegen:

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

Siehe das Haupt-Quickstart-Leitfaden für Details.

Eigenständige Updates

Hosten Sie Ihren eigenen Update-Server:

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

Ihr Server sollte folgendes zurückgeben:

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

Siehe Eigenständiger Modus für vollständige Details.

Manueller Update-Flow

Vollständige Kontrolle über Updates:

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

• Immer aufrufen notifyAppReady() als Ihre App erfolgreich geladen wird
• Updates gründlich testen, bevor Sie sie in die Produktion pusht
• Fehlerbehandlung für Netzwerkfehler implementieren
• Versionen konsistent verwenden
• Bündelgrößen klein halten, um die Herunterladegeschwindigkeit zu erhöhen
• Update-Erfolgsraten überwachen

Schritte für die Zukunft

• Plugin API-Referenz - Fertige API-Dokumentation
• Plugin-Einstellungen - Alle Konfigurationsoptionen
• Events - Verfügbare Aktualisierungsereignisse
• Selbstgeführter Modus - Führen Sie Ihren eigenen Update-Server aus
• Lokale Entwicklung - Testen Sie Updates lokal
• Fehlersuche - Fehlerbehebungshandbuch

Unterstützung

• Bekannte Probleme - Gemeinsame Probleme und Lösungen
• GitHub Diskussionen - Gemeinschaftsunterstützung
• Discord - Echtzeit-Chat

Fortsetzung von Getting Started

Wenn Sie Unterstützung benötigen Einstieg um native Plugin-Arbeit zu planen, verbinden Sie es mit Mit @capgo/capacitor-Updater für die native Fähigkeit in Mit @capgo/capacitor-Updater, Capgo Plugin-Verzeichnis für den Produktworkflow in Capgo Plugin-Verzeichnis, Capacitor Plugins von Capgo für die Implementierungsdetails in Capacitor Plugins von Capgo, Plugins hinzufügen oder aktualisieren für die Implementierungsdetails in Plugins hinzufügen oder aktualisieren, und Ionic Enterprise Plugin Alternativen für den Produktworkflow in Ionic Enterprise Plugin Alternativen.