Utilisation de Capgo en Chine

If you’re deploying your app to users in China, you’ll need to configure Capgo to use regional OST (Object Storage Technology) URLs to ensure reliable and fast updates.

Pourquoi Utiliser des URL Spécifiques à la Chine ?

Due to network infrastructure and regulations in China (the Great Firewall), direct connections to international servers can be slow or unreliable. Capgo provides dedicated OST URLs with data located in Hong Kong to minimize latency and ensure your users receive updates as quickly and reliably as possible.

Configuration

To configure Capgo for China, you need to set three specific URLs in your Capacitor configuration file. These URLs point to Capgo’s Hong Kong-based infrastructure.

1. Ouvrez votre capacitor.config.ts fichier

2. Ajoutez la configuration suivante à la section CapacitorUpdater plugin : 

   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. Reconstruire votre application pour appliquer les modifications :

   npm run build
   npx cap sync

Détails de la configuration

Voici ce que chaque URL fait :

• updateUrl: https://updater.capgo.com.cn/updates - Utilisé pour vérifier et télécharger les mises à jour disponibles pour votre application
• statsUrl: https://updater.capgo.com.cn/stats - Utilisé pour signaler les statistiques d'analyse et d'utilisation vers Capgo
• channelUrl: https://updater.capgo.com.cn/channel_self - Utilisé pour récupérer la configuration du canal et déterminer les mises à jour à appliquer

Conseil

Tous les trois URL doivent être configurés ensemble pour garantir la pleine fonctionnalité de l'Capgo metteur à jour en Chine.

Réglages recommandés pour la Chine

En raison des limitations de performance du réseau causées par le Grand Mur de Chine, nous avons des recommandations spécifiques pour les applications déployées en Chine continentale :

Augmenter le temps de réponse de API

Le plugin de mise à jour Capgo interrompt les appels API lorsque responseTimeout est dépassé (la valeur est en secondes). L'infrastructure Edge devant Capgo traite également environ secondes comme un budget de failure pour certaines routes.

En Chine continentale, la latence transfrontalière est souvent plus élevée. Gardez un responseTimeout pour que le plugin ait suffisamment de place pour terminer les vérifications et les téléchargements de mise à jour par le biais de updater.capgo.com.cn au lieu de failir tôt :

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

Conseil

Préférez responseTimeout: 60 (ou supérieur) pour les déploiements en Chine. Un temps d'attente bas ne fait pas les mises à jour plus rapides — il ne fait que faire abandonner le plugin alors que la requête peut toujours réussir du côté de Capgo.

Utilisez les mises à jour en arrière-plan

Nous recommandons vivement d'utiliser autoUpdate: 'atBackground' pour les applications en Chine. La connectivité réseau en Chine est moins performante que dans les autres régions, et les modes d'application instantanés peuvent entraîner une expérience utilisateur dégradée si les téléchargements sont interrompus ou lents.

En revanche, utilisez le comportement de mise à jour par défaut où les mises à jour téléchargent en arrière-plan et s'appliquent lorsque l'application est en arrière-plan ou redémarre. Cela fournit une expérience plus fiable pour vos utilisateurs.

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

Attention

Même si notre infrastructure basée à Hong Kong aide à minimiser la latence et à améliorer la fiabilité, la performance réseau vers la Chine continentale peut encore être affectée par le Grand Mur Chinois. L'utilisation de mises à jour en arrière-plan aide à s'assurer que les mises à jour se terminent avec succès sans perturber l'expérience de l'utilisateur.

Exemple de Configuration Complète

Voici un exemple complet avec les paramètres recommandés pour les applications déployées en Chine :

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;

Tester votre Configuration

Après avoir configuré les URL spécifiques à la Chine, vous pouvez vérifier que les mises à jour fonctionnent correctement :

1. Télécharger un nouveau bundle vers Capgo :

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

2. Installer votre application sur un appareil de test en Chine

3. Surveiller le processus de mise à jour :

   npx @capgo/cli@latest app debug

4. Vérifiez que les mises à jour sont téléchargées à partir des URL OST de Chine

Remarque

Le comportement et la fréquence des mises à jour restent les mêmes que dans la configuration standard Capgo. Consultez la Comportement de mise à jour documentation pour plus d'informations sur la manière et le moment où les mises à jour sont appliquées.

Déploiement multi-région

Si votre application sert des utilisateurs à la fois à l'intérieur et à l'extérieur de Chine, vous pouvez utiliser la configuration de domaine chinois pour tous les utilisateurs dans le monde. Le updater.capgo.com.cn domaine est résolu à l'échelle mondiale grâce à l'infrastructure DNS d'Alibaba, ce qui le rend accessible à la fois à l'intérieur de Chine et dans le reste du monde.

Utilisation de domaines chinois à l'échelle mondiale

Les URL des domaines chinois fonctionnent de manière fluide pour les applications multi-région :

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

Cette seule configuration fonctionnera pour :

• Utilisateurs de la Chine continentale (en utilisant une infrastructure basée à Hong Kong)
• Utilisateurs hors de Chine (accédant à la même infrastructure via DNS Alibaba)

Considérations de performance :

Même si le .cn domaine est résolu à l'échelle mondiale via DNS Alibaba et fonctionne partout, il est légèrement moins performant pour les utilisateurs hors de Chine par rapport au domaine standard (api.capgo.app), qui est résolu directement par Cloudflare où notre backend est hébergé. Cependant, la résolution DNS est rapide, donc la différence de performance est minime et ne nuira pas significativement à l'expérience utilisateur.

Conseil

En utilisant le .cn domaine pour tous les utilisateurs simplifie votre déploiement et garantit un comportement d'actualisation cohérent dans toutes les régions. Vous n'avez pas besoin de builds séparés ou de configurations basées sur l'environnement. Le petit coût de performance en dehors de la Chine est généralement digne de la simplification du déploiement.

Alternative : Configurations Région-Spécifiques

Si vous préférez optimiser différemment pour chaque région, vous pouvez également considérer :

• Construire des variantes d'applications séparées avec des configurations différentes
• Utiliser une configuration basée sur l'environnement pour définir dynamiquement les URL
• Créer différents canaux de mise à jour pour différentes régions

Si vous avez besoin d'assistance pour les stratégies de déploiement multi-région, veuillez nous contacter à support@capgo.app ou rejoignez notre Communauté Discord Aidez-vous.

Surveillance de l'infrastructure de Chine

Vous pouvez surveiller l'état de santé et le statut des points de terminaison spécifiques à la Chine de Capgo à l'adresse status.capgo.com.cn. Utilisez cette page pour vérifier les incidents, les latences et les temps d'arrêt des URLs OST de Chine avant de résoudre les problèmes de votre application.

Résolution des problèmes

Section intitulée « Résolution des problèmes »

1. Si vous rencontrez des problèmes avec les mises à jour en Chine : Vérifiez votre configuration : - Vérifiez que les trois URLs sont correctement configurées dans votre capacitor.config.ts
2. Augmenter responseTimeout - Utilisez au moins 60 secondes en Chine afin que le plugin ne se bloque pas alors que la demande de mise à jour est toujours en cours de vol
3. Vérifiez la connectivité réseau - Assurez-vous que votre appareil puisse atteindre le updater.capgo.com.cn domaine
4. Vérifiez la page de statut de Chine - Vérifiez statut.capgo.com.cn pour toute incident en cours ou une performance dégradée
5. Examinez les journaux - Utilisez npx @capgo/cli@latest app debug vérifier les messages d'erreur
6. Mises à jour de test - Essayez d'uploader un nouveau bundle et de surveiller le processus de téléchargement
7. Contactez le support - Si les problèmes persistent, nous vous invitons à nous contacter à support@capgo.app ou rejoignez notre communauté Discord pour obtenir de l'aide

Attention

Assurez-vous d'utiliser le .cn domain (updater.capgo.com.cnet pas le domaine international standard lors de la configuration pour la Chine.

Étapes suivantes

• En savoir plus sur Comportement de mise à jour pour personnaliser l'application des mises à jour
• Découvrez Canaux pour gérer différents itinéraires de mise à jour
• Examinez Chiffrement pour sécuriser vos mises à jour

Continuez à partir de l'utilisation de Capgo en Chine

Si vous utilisez L'utilisation de Capgo en Chine pour planifier la livraison des mises à jour en direct, connectez-l’avec Capgo Mises à jour en direct for the product workflow in Capgo Live Updates, pour le flux de travail du produit dans __CAPGO_KEEP_0__ Mises à jour en direct, Vue d'ensemble pour les détails d'implémentation dans Vue d'ensemble, Fonctionnalités Comportement de mise à jour pour le détail d'implémentation dans Comportement de mise à jour, et Types de mise à jour pour le détail d'implémentation dans Types de mise à jour.