Nutzung von Capgo in China

Wenn du deine App an Nutzer in China ausrollst, musst du Capgo so konfigurieren, dass regionale OST (Object Storage Technology) URLs verwendet werden, um zuverlässige und schnelle Updates zu gewährleisten.

Warum China-spezifische URLs nutzen?

Aufgrund der Netzwerkinfrastruktur und der Regulierung in China (Great Firewall) können direkte Verbindungen zu internationalen Servern langsam oder unzuverlässig sein. Capgo bietet dedizierte OST-URLs mit Serverstandort in Hongkong an, um die Latenz zu minimieren und sicherzustellen, dass Ihre Nutzer Updates so schnell und zuverlässig wie möglich erhalten.

Konfiguration

Um Capgo für China zu konfigurieren, müssen Sie drei spezifische URLs in Ihrer Capacitor Konfigurationsdatei festlegen. Diese URLs verweisen auf die Hongkong-basierte Infrastruktur von Capgo.

1. Öffnen Sie Ihre capacitor.config.ts Datei

2. Fügen Sie die folgende Konfiguration im CapacitorUpdater Plugin-Bereich hinzu:

   import { CapacitorConfig } from '@capacitor/cli';
   
   const config: CapacitorConfig = {
     plugins: {
       CapacitorUpdater: {
         autoUpdate: 'atBackground',
         updateUrl: 'https://updater.capgo.com.cn/updates',
         statsUrl: 'https://updater.capgo.com.cn/stats',
         channelUrl: 'https://updater.capgo.com.cn/channel_self',
       },
     },
   };
   
   export default config;

3. Erstellen Sie Ihre App neu, um die Änderungen anzuwenden:

   npm run build
   npx cap sync

Konfigurationsdetails

Das ist die Funktion der einzelnen URLs:

• updateUrl: https://updater.capgo.com.cn/updates - Wird genutzt, um verfügbare Updates für deine App zu prüfen und herunterzuladen
• statsUrl: https://updater.capgo.com.cn/stats - Wird genutzt, um Analytics und Nutzungsstatistiken an Capgo zu senden
• channelUrl: https://updater.capgo.com.cn/channel_self - Wird genutzt, um die Channel-Konfiguration abzurufen und festzulegen, welche Updates angewendet werden

Tipp

Alle drei URLs müssen gemeinsam konfiguriert werden, um die volle Funktionalität des Capgo Updaters in China zu gewährleisten.

Empfohlene Einstellungen für China

Aufgrund der durch die Great Firewall of China verursachten Einschränkungen der Netzwerkleistung haben wir konkrete Empfehlungen für Apps, die in Festlandchina bereitgestellt werden:

API Response Timeout erhöhen

Das Capgo Updater-Plugin bricht API-Aufrufe ab, wenn responseTimeout überschritten wird (der Wert liegt in Sekunden). Die Edge-Infrastruktur vor Capgo rechnet zudem mit etwa 3 Sekunden als Failure Budget für bestimmte Pfade.

In Festlandchina ist die Latenz bei grenzüberschreitenden Verbindungen oft höher. Setze einen höheren responseTimeout damit das Plugin genügend Zeit hat, Update-Checks und Downloads über updater.capgo.com.cn anstatt vorzeitig abzubrechen:

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      // Seconds. Raise above the default (20) for China network conditions.
      responseTimeout: 60,
      updateUrl: 'https://updater.capgo.com.cn/updates',
      statsUrl: 'https://updater.capgo.com.cn/stats',
      channelUrl: 'https://updater.capgo.com.cn/channel_self',
    },
  },
};

Tipp

Bevorzugen responseTimeout: 60 (oder einen höheren) Timeout für China-Deployments. Ein niedriger Timeout macht Updates nicht schneller – er führt nur dazu, dass das Plugin aufgibt, obwohl die Anfrage auf der Seite von Capgo noch erfolgreich sein könnte.

Background Updates nutzen

Wir wir empfehlen dringend autoUpdate: 'atBackground' für Apps in China. Die Netzwerkverbindung in China ist weniger performant als in anderen Regionen, und Instant-Apply-Modi können zu einer schlechten User Experience führen, wenn Downloads unterbrochen werden oder langsam sind.

Nutze stattdessen das Standard-Update-Verhalten: Updates werden im Hintergrund heruntergeladen und angewendet, wenn die App in den Hintergrund wechselt oder neu startet. Das bietet deinen Nutzern eine zuverlässigere Erfahrung.

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground', // Recommended for China
      updateUrl: 'https://updater.capgo.com.cn/updates',
      statsUrl: 'https://updater.capgo.com.cn/stats',
      channelUrl: 'https://updater.capgo.com.cn/channel_self',
    },
  },
};

Achtung

Obwohl unsere Infrastruktur in Hongkong hilft, Latenzen zu minimieren und die Zuverlässigkeit zu erhöhen, kann die Netzwerkperformance nach Festlandchina weiterhin durch die Great Firewall beeinträchtigt werden. Background-Updates helfen, Updates erfolgreich abzuschließen, ohne die User Experience zu stören.

Vollständiges Konfigurationsbeispiel

Hier ist ein vollständiges Beispiel mit den empfohlenen Einstellungen für in China bereitgestellte Apps:

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'My App',
  webDir: 'dist',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground', // Recommended for better reliability in China
      responseTimeout: 60, // Seconds — give China network more room
      updateUrl: 'https://updater.capgo.com.cn/updates',
      statsUrl: 'https://updater.capgo.com.cn/stats',
      channelUrl: 'https://updater.capgo.com.cn/channel_self',
    },
  },
};

export default config;

Konfiguration testen

Nachdem du die China-spezifischen URLs konfiguriert hast, kannst du prüfen, ob die Updates korrekt funktionieren:

1. Lade ein neues Bundle bei Capgo hoch:

   npx @capgo/cli@latest bundle upload --channel=production

2. Installiere deine App auf einem Testgerät in China

3. Überwache den Update-Prozess:

   npx @capgo/cli@latest app debug

4. Prüfe, ob die Updates von den China OST-URLs heruntergeladen werden

Hinweis

Das Update-Verhalten und -Timing bleiben gleich wie bei der Standard-Konfiguration von Capgo. Siehe die Update-Verhalten Dokumentation für Details dazu, wie und wann Updates angewendet werden.

Multi-Region-Deployment

Wenn Ihre App Nutzer sowohl innerhalb als auch außerhalb Chinas bedient, können Sie die chinesische Domain-Konfiguration für alle Nutzer weltweit verwenden. Die updater.capgo.com.cn Domain wird dank der Alibaba DNS-Infrastruktur global aufgelöst und ist damit sowohl in China als auch überall sonst auf der Welt erreichbar.

Chinesische Domains weltweit nutzen

Die URLs der chinesischen Domain funktionieren nahtlos für Multi-Region-Apps:

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground', // Recommended for China users
      updateUrl: 'https://updater.capgo.com.cn/updates',
      statsUrl: 'https://updater.capgo.com.cn/stats',
      channelUrl: 'https://updater.capgo.com.cn/channel_self',
    },
  },
};

Diese eine Konfiguration funktioniert für:

• Nutzer in Festlandchina (via Infrastruktur in Hongkong)
• Nutzer außerhalb Chinas (die über denselben Alibaba DNS auf die Infrastruktur zugreifen)

Performance-Hinweise:

Während die .cn Domain weltweit über Alibaba DNS aufgelöst wird und überall funktioniert, ist sie für Nutzer außerhalb Chinas etwas weniger performant als die Standard-Domain (api.capgo.app), die direkt von Cloudflare aufgelöst wird, wo unser Backend gehostet wird. Die DNS-Auflösung ist jedoch schnell, sodass der Performance-Unterschied minimal ist und die User Experience kaum beeinflusst.

Tipp

Mit dem .cn Domain für alle Nutzer dein Deployment vereinfacht und ein konsistentes Update-Verhalten über alle Regionen hinweg sicherstellt. Du benötigst keine separaten Builds oder umgebungsbasierte Konfigurationen. Der geringe Performance-Verlust außerhalb Chinas lohnt sich meist durch das einfachere Deployment.

Alternative: Regionspezifische Konfigurationen

Falls Sie jede Region unterschiedlich optimieren möchten, können Sie auch Folgendes in Betracht ziehen:

• Erstellen separater App-Varianten mit unterschiedlichen Konfigurationen
• Nutzung von Umgebungsvariablen, um URLs dynamisch zu setzen
• Erstellen verschiedener Release-Channels für unterschiedliche Regionen

Falls Sie Unterstützung bei Multi-Region-Deployment-Strategien benötigen, kontaktieren Sie uns unter support@capgo.app or join our Discord-Community für Hilfe.

Überwachung der China-Infrastruktur

Sie können den Status und die Verfügbarkeit der China-spezifischen Endpunkte von Capgo hier überwachen: Status von capgo.com.cn. Nutze diese Seite, um Incidents, Latenz und Uptime der China OST URLs zu prüfen, bevor du deine App troubleshootest.

Fehlerbehebung

Falls du Probleme mit Updates in China hast:

1. Konfiguration prüfen - Überprüfe, ob alle drei URLs korrekt gesetzt sind in deiner capacitor.config.ts
2. Erhöhen responseTimeout - Nutze mindestens 60 Sekunden in China, damit das Plugin nicht abbricht, während der Update-Request noch läuft
3. Netzwerkverbindung prüfen - Stelle sicher, dass dein Gerät den updater.capgo.com.cn Domain
4. China-Statusseite prüfen - Prüfe status.capgo.com.cn auf laufende Incidents oder Performance-Einbußen
5. Logs prüfen - Nutze npx @capgo/cli@latest app debug um nach Fehlermeldungen zu suchen
6. Updates testen - Versuche, ein neues Bundle hochzuladen und den Download-Prozess zu überwachen
7. Support kontaktieren - Falls Probleme weiterhin bestehen, kontaktiere uns unter support@capgo.app oder tritt unserem Discord-Community für Unterstützung bei

Achtung

Verwende unbedingt die .cn Domain (updater.capgo.com.cn) statt der Standard-Domain, wenn du die Konfiguration für China vornimmst.

Nächste Schritte

• Mehr über Update-Verhalten um festzulegen, wann Updates angewendet werden
• Entdecken Kanäle um verschiedene Release-Tracks zu verwalten
• Überprüfen Verschlüsselung um deine Updates abzusichern

Weiter mit der Nutzung von Capgo in China

Wenn du es nutzt Nutzung von Capgo in China um die Auslieferung von live update zu planen, verbinde sie mit Capgo Live Updates für den Produkt-Workflow in Capgo Live Updates, Übersicht für die Implementierungsdetails in Overview, Funktionen für die Implementierungsdetails in Features, Update-Verhalten für die Implementierungsdetails in Update Behavior und Update-Typen für die Implementierungsdetails in Update Types.