Erste Schritte

Installation

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

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

Nutze dann diesen Prompt:

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

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

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 Nutzer empfehlen wir den Haupt-Quickstart-Guide der sowohl die Plugin-Installation als auch die Capgo Cloud-Integration abdeckt.

Dieser Getting-started-Guide konzentriert sich auf die technischen Plugin-Details für fortgeschrittene Nutzer, die die zugrunde liegenden Mechanismen verstehen oder Self-hosted Updates umsetzen möchten.

Übersicht

Das Capacitor Updater Plugin ermöglicht Over-the-Air (OTA) Updates für deine Capacitor Apps. So kannst du Updates direkt pushen, ohne den Review-Prozess der App Stores abzuwarten.

So funktioniert es

1. Bundle-Download: Das Plugin lädt Update-Bundles herunter (ZIP-Dateien mit deinen Web-Assets)
2. Entpacken: Die Bundles werden im lokalen Speicher des Geräts entpackt
3. Hot Reload: Die App wechselt zum neuen Bundle, ohne dass ein Neustart nötig ist
4. Fallback: Schlägt ein Update fehl, kehrt die App zur letzten funktionierenden Version zurück

Nutzungsmodi

1. Auto-Update-Modus (Empfohlen)

Der einfachste Weg, das Plugin mit automatischem Update-Management zu nutzen:

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

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

Add to your capacitor.config.ts:

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

2. Manueller Modus

Für erweiterte 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();

Plattformkonfiguration

iOS

Keine weitere Konfiguration erforderlich. Das Plugin funktioniert sofort.

Android

Keine weitere Konfiguration erforderlich. Das Plugin funktioniert sofort.

Grundlegende API Nutzung

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 festlegen

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

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

Auf Update-Events hören:

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

Konfiguriere das Plugin in deinem 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'
    }
  }
}

Integrationsmuster

Mit Capgo Cloud

Der einfachste Einstieg:

// 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 den Haupt-Quickstart-Guide für Details.

Self-Hosted Updates

Hoste deinen eigenen Update-Server:

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

Dein Server sollte Folgendes zurückgeben:

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

Siehe Self-Hosted-Modus für alle Details.

Manueller Update-Flow

Volle 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() wenn deine App erfolgreich lädt
• Updates gründlich testen, bevor du sie nach Production pushst
• Fehlerbehandlung für Netzwerkfehler implementieren
• Versionsnummern konsistent verwenden
• Bundle-Größen klein halten für schnellere Downloads
• Erfolgsraten der Updates überwachen

Nächste Schritte

• Plugin API Referenz - API Dokumentation abschließen
• Plugin-Einstellungen - Alle Konfigurationsoptionen
• Events - Verfügbare Update-Events
• Self-Hosted Modus - Eigener Update-Server
• Lokale Entwicklung - Updates lokal testen
• Debugging - Troubleshooting-Guide

Support

• Bekannte Probleme - Häufige Probleme und Lösungen
• GitHub Diskussionen - Community-Support
• Discord - Echtzeit-Chat

Weiter geht's nach Getting Started

Wenn du es nutzt Erste Schritte Um die Arbeit an nativen Plugins zu planen, verbinde sie mit Verwendung von @capgo/capacitor-updater für die native Funktion in der Verwendung von @capgo/capacitor-updater, Capgo Plugin-Verzeichnis für den Produkt-Workflow im Capgo Plugin-Verzeichnis, Capacitor Plugins von Capgo für das Implementierungsdetail in Capacitor Plugins von Capgo, Plugins hinzufügen oder aktualisieren für das Implementierungsdetail beim Hinzufügen oder Aktualisieren von Plugins, und Ionic Enterprise Plugin-Alternativen für den Produkt-Workflow bei den Ionic Enterprise Plugin-Alternativen.