Utiliser Capgo en Chine

Si vous déployez votre application pour des utilisateurs en Chine, vous devez configurer Capgo afin d'utiliser des URL OST (Object Storage Technology) régionales pour garantir des mises à jour fiables et rapides.

Pourquoi utiliser des URL spécifiques à la Chine ?

En raison de l'infrastructure réseau et des réglementations en Chine (le Great Firewall), les connexions directes vers les serveurs internationaux peuvent être lentes ou instables. Capgo fournit des URL OST dédiées avec des données situées à Hong Kong pour minimiser la latence et garantir que vos utilisateurs reçoivent les mises à jour aussi rapidement et de manière aussi fiable que possible.

Configuration

Pour configurer Capgo pour la Chine, vous devez définir trois URL spécifiques dans votre fichier de configuration Capacitor. Ces URL pointent vers l'infrastructure de Capgo basée à Hong Kong.

1. Ouvrez votre capacitor.config.ts fichier

2. Ajoutez la configuration suivante à la CapacitorUpdater section 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. Recompilez votre app pour appliquer les changements :

   npm run build
   npx cap sync

Détails de la configuration

Voici le rôle de chaque URL :

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

Astuce

Ces trois URL doivent être configurées ensemble pour garantir le fonctionnement complet de l'updater Capgo en Chine.

Paramètres recommandés pour la Chine

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

Augmenter le timeout de réponse de API

Le plugin updater Capgo interrompt les appels API quand responseTimeout est dépassé (la valeur est en secondes). L'infrastructure edge devant Capgo traite également environ 3 secondes comme budget d'erreur pour certains chemins.

En Chine continentale, la latence transfrontalière est souvent plus élevée. Prévoyez un responseTimeout pour que le plugin ait assez de marge pour terminer les vérifications et les téléchargements via updater.capgo.com.cn au lieu d'échouer prématurément :

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

Astuce

Privilégiez responseTimeout: 60 (ou plus élevé) pour les déploiements en Chine. Un timeout court ne rend pas les mises à jour plus rapides — il force simplement le plugin à abandonner alors que la requête pourrait réussir du côté de Capgo.

Utiliser les mises à jour en arrière-plan

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

Utilisez plutôt le comportement de mise à jour par défaut, où les mises à jour se téléchargent en arrière-plan et s'appliquent lorsque l'app passe en arrière-plan ou redémarre. Cela offre une expérience plus fiable à 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

Bien que notre infrastructure basée à Hong Kong contribue à réduire la latence et à améliorer la fiabilité, les performances réseau vers la Chine continentale peuvent encore être affectées par le Great Firewall. Le recours aux mises à jour en arrière-plan permet de s'assurer qu'elles aboutissent sans perturber l'expérience utilisateur.

Exemple de configuration complète

Voici un exemple complet avec les paramètres recommandés pour les apps 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 Live Update fonctionnent correctement :

1. Envoyez un nouveau bundle vers Capgo :

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

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

3. Surveillez le processus de mise à jour :

   npx @capgo/cli@latest app debug

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

Remarque

Le comportement et le timing des mises à jour restent identiques à une configuration Capgo standard. Voir la Comportement de mise à jour documentation pour savoir comment et quand les mises à jour sont appliquées.

Déploiement multi-régions

Si votre application s'adresse à des utilisateurs en Chine et à l'étranger, vous pouvez utiliser la configuration de domaine chinoise pour tous les utilisateurs dans le monde. Le updater.capgo.com.cn le domaine est résolu mondialement grâce à l'infrastructure DNS d'Alibaba, le rendant accessible aussi bien en Chine qu'ailleurs dans le monde.

Utiliser des domaines chinois à l'échelle mondiale

Les URL des domaines chinois fonctionnent parfaitement pour les applications multiré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 configuration unique convient pour :

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

Considérations de performance :

Bien que le .cn domaine soit résolu mondialement via le DNS Alibaba et fonctionne partout, il est légèrement moins performant pour les utilisateurs hors de Chine que le domaine standard (api.capgo.app), qui est résolu directement par Cloudflare là où notre backend est hébergé. Cependant, la résolution DNS est rapide : la différence de performance est minime et n'aura pas d'impact significatif sur l'expérience utilisateur.

Astuce

L'utilisation du .cn domaine pour tous les utilisateurs simplifie votre déploiement et garantit un comportement de mise à jour cohérent dans toutes les régions. Vous n'avez pas besoin de builds séparés ni de configurations par environnement. Le léger compromis de performance hors de Chine est généralement acceptable en échange d'un déploiement simplifié.

Alternative : configurations par région

Si vous préférez optimiser différemment chaque région, vous pouvez aussi envisager de :

• Créer des variantes d'app distinctes avec des configurations différentes
• Utiliser une configuration basée sur l'environnement pour définir les URL dynamiquement
• Créer différents canaux de release pour chaque région

Si vous avez besoin d'aide pour vos stratégies de déploiement multi-régions, contactez-nous à support@capgo.app ou rejoignez notre communauté Discord for help.

Surveiller l'infrastructure en Chine

Vous pouvez surveiller l'état et la santé des endpoints spécifiques à la Chine de Capgo sur status.capgo.com.cn. Utilisez cette page pour vérifier les incidents, la latence et la disponibilité des URL OST en Chine avant de dépanner votre application.

Troubleshooting

Si vous rencontrez des problèmes de mise à jour en Chine :

1. Vérifiez votre configuration - Vérifiez bien que les trois URL sont correctement configurées dans votre capacitor.config.ts
2. Augmenter responseTimeout - Utilisez au moins 60 secondes en Chine pour éviter que le plugin n'interrompe la requête de mise à jour en cours
3. Vérifier la connectivité réseau - Assurez-vous que votre appareil peut accéder au updater.capgo.com.cn domaine
4. Consulter la page de statut Chine - Examiner status.capgo.com.cn pour détecter d'éventuels incidents ou une baisse de performance
5. Examiner les logs - Utiliser npx @capgo/cli@latest app debug pour vérifier les messages d'erreur
6. Tester les mises à jour - Essayer d'envoyer un nouveau bundle et surveiller le processus de téléchargement
7. Contacter le support - Si les problèmes persistent, contactez-nous à support@capgo.app ou rejoignez notre communauté Discord pour obtenir de l'aide

Attention

Assurez-vous d'utiliser le .cn domaine (updater.capgo.com.cn) et non le domaine international standard lors de la configuration pour la Chine.

Étapes suivantes

• En savoir plus sur Comportement de mise à jour to customize when updates are applied
• Explorer Canaux pour gérer différents canaux de release
• Examiner Chiffrement pour sécuriser vos mises à jour

Continuer depuis « Utiliser Capgo en Chine »

Si vous utilisez Utiliser Capgo en Chine pour planifier la livraison de live update, connectez-l’à Capgo Live Updates pour le workflow produit dans Capgo Live Updates, Aperçu pour les détails d'implémentation dans Vue d'ensemble, Fonctionnalités pour le détail d’implémentation dans Fonctionnalités, Comportement de mise à jour pour les détails d'implémentation dans Update Behavior, et Types de mise à jour pour les détails d'implémentation dans Update Types.