Utilizzo di Capgo in Cina

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

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 minimizzare la latenza e assicurare che i tuoi utenti ricevano aggiornamenti nel modo più rapido e affidabile 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 file capacitor.config.ts

2. Aggiungi la seguente configurazione alla sezione plugin CapacitorUpdater:

   import { CapacitorConfig } from '@capacitor/cli';
   
   const config: CapacitorConfig = {
     plugins: {
       CapacitorUpdater: {
         autoUpdate: true,
         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 Configurazione

Ecco cosa fa ogni URL:

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

Suggerimento

Tutti e tre gli URL devono essere configurati insieme per garantire la piena funzionalità dell’updater Capgo in Cina.

Impostazioni Consigliate per la Cina

A causa delle limitazioni di prestazioni di rete causate dal Great Firewall of China, abbiamo raccomandazioni specifiche per le app distribuite nella Cina continentale:

Disabilita Aggiornamenti Diretti

Raccomandiamo fortemente di disabilitare directUpdate per le app in Cina. La connettività di rete in Cina è meno performante rispetto ad altre regioni, e gli aggiornamenti diretti (che si applicano immediatamente) possono portare a una scarsa esperienza utente se i download vengono interrotti o sono lenti.

Invece, usa il comportamento predefinito di aggiornamento dove gli aggiornamenti vengono scaricati in background e applicati quando l’app va in background o si riavvia. Questo fornisce un’esperienza più affidabile per i tuoi utenti.

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      directUpdate: false, // Consigliato per la Cina
      updateUrl: 'https://updater.capgo.com.cn/updates',
      statsUrl: 'https://updater.capgo.com.cn/stats',
      channelUrl: 'https://updater.capgo.com.cn/channel_self',
    },
  },
};

Attenzione

Mentre la nostra infrastruttura basata a Hong Kong aiuta a minimizzare la latenza e migliorare l’affidabilità, le prestazioni di rete verso la Cina continentale possono ancora essere influenzate dal Great Firewall. Disabilitare directUpdate aiuta ad assicurare che gli aggiornamenti si completino con successo senza interrompere l’esperienza utente.

Esempio di Configurazione Completa

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

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

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'My App',
  webDir: 'dist',
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      directUpdate: false, // Consigliato: disabilita per migliore affidabilità in Cina
      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;

Testare la Tua 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. Controlla che gli aggiornamenti vengano scaricati dagli URL OST Cina

Nota

Il comportamento e la tempistica dell’aggiornamento rimangono gli stessi della configurazione standard Capgo. Consulta la documentazione Comportamento Aggiornamento per dettagli su come e quando gli aggiornamenti vengono applicati.

Distribuzione Multi-Regione

Se la tua app serve utenti sia dentro che fuori la Cina, puoi usare la configurazione dominio cinese per tutti gli utenti nel mondo. Il dominio updater.capgo.com.cn viene risolto globalmente grazie all’infrastruttura DNS Alibaba, rendendolo accessibile sia in Cina che ovunque nel mondo.

Utilizzo Domini Cinesi Globalmente

Gli URL dominio cinese funzionano perfettamente per app multi-regione:

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      directUpdate: false, // Consigliato per utenti Cina
      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 (usando infrastruttura basata a Hong Kong)
• Utenti fuori dalla Cina (accedendo alla stessa infrastruttura tramite DNS Alibaba)

Considerazioni sulle Prestazioni:

Mentre il dominio .cn viene risolto globalmente tramite DNS Alibaba e funziona ovunque, è leggermente meno performante per 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 prestazioni è minima e non impatterà significativamente l’esperienza utente.

Suggerimento

Usare il dominio .cn per tutti gli utenti semplifica il tuo deployment e assicura un comportamento di aggiornamento consistente in tutte le regioni. Non hai bisogno di build separate o configurazioni basate sull’ambiente. Il piccolo compromesso nelle prestazioni fuori dalla Cina vale tipicamente la pena per il deployment semplificato.

Alternativa: Configurazioni Specifiche per Regione

Se preferisci ottimizzare diversamente per ogni regione, puoi anche considerare:

• Costruire varianti app separate con configurazioni diverse
• Usare configurazione basata sull’ambiente per impostare dinamicamente gli URL
• Creare canali di rilascio diversi per regioni diverse

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

Risoluzione dei Problemi

Se riscontri problemi con gli aggiornamenti in Cina:

1. Verifica la tua configurazione - Ricontrolla che tutti e tre gli URL siano impostati correttamente nel tuo capacitor.config.ts
2. Controlla connettività di rete - Assicurati che il tuo dispositivo possa raggiungere il dominio updater.capgo.com.cn
3. Rivedi i log - Usa npx @capgo/cli@latest app debug per controllare messaggi di errore
4. Testa aggiornamenti - Prova a caricare un nuovo bundle e monitora il processo di download
5. Contatta supporto - Se i problemi persistono, contattaci a support@capgo.app o unisciti alla nostra community Discord per assistenza

Attenzione

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

Prossimi Passi

• Scopri di più sul Comportamento Aggiornamento per personalizzare quando gli aggiornamenti vengono applicati
• Esplora Canali per gestire diverse tracce di rilascio
• Rivedi Crittografia per proteggere i tuoi aggiornamenti