Usare Capgo in Cina

Se stai distribuendo la tua app in Cina, dovrai configurare Capgo per utilizzare gli URL regionali OST (Object Storage Technology) per garantire aggiornamenti rapidi e affidabili.

Perché usare URL specifici per la Cina?

A causa dell'infrastruttura di rete e delle normative in Cina (il Great Firewall), le connessioni dirette ai server internazionali possono essere lente o inaffidabili. Capgo fornisce URL OST dedicati con dati situati a Hong Kong per ridurre al minimo la latenza e garantire che i tuoi utenti ricevano gli aggiornamenti il più velocemente e affidabilmente possibile.

Configurazione

Per configurare Capgo per la Cina, devi impostare tre URL specifici nel tuo file di configurazione Capacitor. Questi URL puntano all'infrastruttura di Capgo basata a Hong Kong.

1. Apri il tuo capacitor.config.ts file

2. Aggiungi la seguente configurazione alla CapacitorUpdater sezione 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. Ricompila la tua app per applicare le modifiche:

   npm run build
   npx cap sync

Dettagli di configurazione

Ecco la funzione di ogni URL:

• updateUrl: https://updater.capgo.com.cn/updates - Utilizzato per controllare e scaricare gli update disponibili per la tua app
• statsUrl: https://updater.capgo.com.cn/stats - Utilizzato per inviare analytics e statistiche di utilizzo a Capgo
• channelUrl: https://updater.capgo.com.cn/channel_self - Utilizzato per recuperare la configurazione del canale e determinare quali update applicare

Tip

Tutti e tre gli URL devono essere configurati insieme per garantire il pieno funzionamento dell'updater Capgo in Cina.

Impostazioni consigliate per la Cina

A causa dei limiti di rete causati dal Great Firewall cinese, abbiamo raccomandazioni specifiche per le app distribuite nella Cina continentale:

Aumentare il timeout di risposta di API

Il plugin updater di Capgo interrompe le chiamate API quando responseTimeout viene superato (il valore è in secondi). Anche l'infrastruttura edge davanti a Capgo impiega circa 3 secondi come budget di errore per alcuni percorsi.

In Cina continentale, la latenza transfrontaliera è spesso più alta. Mantieni un valore più alto responseTimeout così il plugin ha spazio sufficiente per completare i controlli e i download degli update tramite updater.capgo.com.cn invece di fallire prematuramente:

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

Tip

Preferisci responseTimeout: 60 (o superiore) per i deployment in Cina. Un timeout basso non velocizza gli update: causa solo l'interruzione del plugin mentre la richiesta potrebbe ancora avere successo lato Capgo.

Usa Background Updates

Noi consigliamo vivamente di usare autoUpdate: 'atBackground' per le app in Cina. La connettività di rete in Cina è meno performante rispetto ad altre regioni; le modalità di applicazione istantanea possono causare una scarsa esperienza utente se i download vengono interrotti o sono lenti.

Invece, usa il comportamento di aggiornamento predefinito, in cui gli update vengono scaricati in background e applicati quando l'app passa in background o viene riavviata. Questo offre un'esperienza più affidabile ai tuoi utenti.

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

Attenzione

Sebbene la nostra infrastruttura basata a Hong Kong aiuti a ridurre la latenza e migliorare l'affidabilità, le prestazioni di rete verso la Cina continentale possono essere influenzate dal Great Firewall. L'uso degli update in background aiuta a garantire che gli update vengano completati con successo senza interrompere l'esperienza utente.

Esempio di configurazione completa

Ecco un esempio completo con le impostazioni consigliate per le app distribuite in Cina:

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;

Test della configurazione

Dopo aver configurato gli URL specifici per la Cina, puoi verificare che gli aggiornamenti funzionino correttamente:

1. Carica un nuovo bundle su Capgo:

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

2. Installa la tua app su un dispositivo di test in Cina

3. Monitora il processo di aggiornamento:

   npx @capgo/cli@latest app debug

4. Verifica che gli aggiornamenti vengano scaricati dagli URL OST della Cina

Nota

Il comportamento e la tempistica degli aggiornamenti restano identici alla configurazione standard di Capgo. Consulta la Comportamento degli aggiornamenti documentazione per i dettagli su come e quando vengono applicati gli aggiornamenti.

Deployment multi-regione

Se la tua app serve utenti sia in Cina che all'estero, puoi usare la configurazione del dominio cinese per tutti gli utenti nel mondo. Il updater.capgo.com.cn dominio viene risolto globalmente grazie all'infrastruttura DNS di Alibaba, rendendolo accessibile sia in Cina che in ogni altra parte del mondo.

Usare i domini cinesi a livello globale

Gli URL del dominio cinese funzionano senza problemi per le app multi-regione:

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

Questa singola configurazione funzionerà per:

• Utenti nella Cina continentale (tramite infrastruttura di Hong Kong)
• Utenti fuori dalla Cina (che accedono alla stessa infrastruttura via Alibaba DNS)

Considerazioni sulle performance:

Sebbene il .cn dominio venga risolto globalmente tramite Alibaba DNS e funzioni ovunque, è leggermente meno performante per gli utenti fuori dalla Cina rispetto al dominio standard (api.capgo.app), che viene risolto direttamente da Cloudflare dove è ospitato il nostro backend. Tuttavia, la risoluzione DNS è veloce, quindi la differenza di performance è minima e non impatterà significativamente l'esperienza utente.

Tip

Utilizzare l' .cn il dominio per tutti gli utenti semplifica il deployment e garantisce un comportamento degli update coerente in tutte le regioni. Non servono build separate o configurazioni basate sull'ambiente. Il piccolo compromesso sulle performance fuori dalla Cina è solitamente ampiamente ripagato dalla semplicità di deployment.

Alternativa: Configurazioni specifiche per regione

Se preferisci ottimizzare in modo diverso per ogni regione, puoi anche considerare:

• Creare varianti dell'app separate con configurazioni diverse
• Usare configurazioni basate su environment per impostare gli URL dinamicamente
• Creare diversi release channel per diverse regioni

Se hai bisogno di assistenza con strategie di deployment multi-regione, contattaci a support@capgo.app o unisciti a noi su community Discord per assistenza.

Monitoraggio dell'infrastruttura in Cina

Puoi monitorare lo stato e la salute degli endpoint di Capgo in Cina su stato di capgo.com.cn. Usa questa pagina per controllare incidenti, latenza e uptime degli URL OST in Cina prima di fare troubleshooting della tua app.

Risoluzione problemi

Se riscontri problemi con gli update in Cina:

1. Verifica la configurazione - Controlla che tutti e tre gli URL siano impostati correttamente in capacitor.config.ts
2. Aumenta responseTimeout - Usa almeno 60 secondi in Cina, in modo che il plugin non si interrompa mentre la richiesta di update è ancora in corso
3. Controlla la connettività di rete - Ensure your device can reach the updater.capgo.com.cn dominio
4. Controlla la pagina di stato per la Cina - Controlla stato di capgo.com.cn per eventuali incidenti o cali di performance
5. Controlla i log - Usa npx @capgo/cli@latest app debug per cercare messaggi di errore
6. Testa gli update - Prova a fare l'upload di un nuovo bundle e monitora il download
7. Contatta il supporto - Se il problema persiste, contattaci a support@capgo.app o unisciti a noi su community Discord per assistenza

Attenzione

Assicurati di usare il .cn dominio (updater.capgo.com.cn) e non il dominio internazionale standard durante la configurazione per la Cina.

Prossimi passi

• Scopri di più su Comportamento degli aggiornamenti per personalizzare l'applicazione degli update
• Esplora Canali per gestire diversi release track
• Revisione Crittografia per mettere in sicurezza i tuoi update

Continua da Usare Capgo in Cina

Se stai usando Usare Capgo in Cina per pianificare la distribuzione di live update, collegalo a Live Updates di Capgo per il workflow del prodotto in Capgo Live Updates, Panoramica per i dettagli di implementazione nell'Overview, Funzionalità per i dettagli implementativi in Features, Comportamento degli aggiornamenti per i dettagli implementativi in Update Behavior, e Tipi di aggiornamento per i dettagli di implementazione in Tipi di aggiornamento.