Anleitung zum Starten

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

Schnellstart

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

Diese Anleitung zur Einführung 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 das Internet (OTA) Updates für Ihre Capacitor-Anwendungen. Dies ermöglicht es Ihnen, Updates an Ihre App zu senden, ohne durch App-Store-Überprüfungen gehen zu müssen.

Wie es funktioniert

1. Paket-Download: Der Plugin lädt Aktualisierungs-Pakete (ZIP-Dateien mit Ihren Web-Ressourcen) herunter
2. Extraktion: Die Pakete werden auf dem Gerätespeicher extrahiert
3. Warmes Neuladen: Die App wechselt zum neuen Paket ohne Neustart erforderlich zu machen
4. Rückfallposition: Wenn eine Aktualisierung fehlschlägt, kehrt die App zur vorherigen funktionierenden Version zurück

Verwendungsmöglichkeiten

1. Automatischer Aktualisierungsmodus (Empfohlen)

Die einfachste Möglichkeit, das Plugin mit automatischer Update-Verwaltung zu verwenden:

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

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

Zum Projekt hinzufügen capacitor.config.ts:

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

2. Manueller Modus

Für eine umfassende Kontrolle über den Update-Prozess:

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 weitere Konfiguration erforderlich. Der Plugin funktioniert direkt aus der Box.

Android

Keine weitere Konfiguration erforderlich. Der Plugin funktioniert direkt aus der Box.

Grundlegende API Verwendung

Download eines Updates

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

Neustart mit neuem Bundle

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

Bundle-Liste

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

Bundle löschen

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

Aktuelles Bundle abrufen

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

Event Listener

Hinweis auf Aktualisierungsevents:

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

Konfigurationsmöglichkeiten

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

Integrationsmuster

Mit Capgo Cloud

Die einfachste Möglichkeit, 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 Hauptanleitung für den Schnellstart für Details.

Selbstgehostete Updates

Hosten Sie Ihren eigenen Update-Server:

// Configure your update endpoint
{
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      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 weitere 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();
}

Gute Praktiken

• Rufen Sie immer notifyAppReady() Testen Sie Updates gründlich, bevor Sie sie in die Produktion puschen
• Implementieren Sie eine ordnungsgemäße Fehlerbehandlung für Netzwerkfehler
• __CAPGO_KEEP_0__
• Verwenden Sie Versionsnummern konsistent
• Halten Sie die Größe der Bundle für schnellere Downloads klein
• Überwachen Sie die Erfolgsraten von Updates

Nächste Schritte

• Plugin API-Referenz - Vollständige API-Dokumentation
• Plugin-Einstellungen - Alle Konfigurationsoptionen
• Events - Verfügbare Update-Events
• Selbstgehosteter Modus - Ihren eigenen Update-Server betreiben
• Lokale Entwicklung - Updates lokal testen
• Fehlersuche - Fehlersuchehilfe

Support

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