Condividi tramite

Cordova Client SDK

  • Articolo

Importante

Visual Studio App Center è pianificato per il ritiro il 31 marzo 2025. Anche se è possibile continuare a usare Visual Studio App Center fino a quando non viene completamente ritirato, esistono diverse alternative consigliate a cui è possibile considerare la migrazione.

Altre informazioni sulle sequenze temporali e sulle alternative di supporto.

Questo plug-in fornisce l'integrazione lato client per il servizio CodePush, consentendo di aggiungere facilmente un'esperienza di aggiornamento dinamico alle app Cordova.

Nota

Il supporto per le app Cordova è terminato nell'aprile 2022. Per altre informazioni, vedere il blog di App Center.

Come funziona?

Un'app Cordova è costituita da file HTML, CSS e JavaScript e da qualsiasi immagine associata, che vengono combinate dall'interfaccia della riga di comando di Cordova e distribuite come parte di un file binario specifico della piattaforma (ad esempio un file con estensione ipa o .apk). Una volta rilasciata l'app, per aggiornare il codice o gli asset di immagine è necessario ricompilare e ridistribuire l'intero file binario. Questo processo include il tempo di revisione per gli archivi in cui si sta pubblicando.

Il plug-in CodePush consente di ottenere immediatamente miglioramenti al prodotto davanti agli utenti finali, mantenendo il codice e le immagini sincronizzati con gli aggiornamenti rilasciati al server CodePush. In questo modo, l'app offre i vantaggi di un'esperienza per dispositivi mobili offline, nonché l'agilità "web-like" degli aggiornamenti sideload non appena sono disponibili. È una soluzione vantaggiosa per tutti!

Per assicurarsi che gli utenti finali abbiano sempre una versione funzionante dell'app, il plug-in CodePush mantiene una copia dell'aggiornamento precedente, in modo che, nel caso in cui si eseva accidentalmente un aggiornamento che includa un arresto anomalo, può eseguire automaticamente il rollback. In questo modo, è possibile assicurarsi che la nuova agilità di rilascio non comporterà il blocco degli utenti prima di avere la possibilità di eseguire il rollback sul server. È una vittoria vincente!

Nota

Le modifiche apportate al prodotto che toccano il codice nativo (ad esempio, l'aggiornamento delle versioni di Cordova, l'aggiunta di un nuovo plug-in) non possono essere distribuite tramite CodePush e quindi devono essere aggiornate tramite gli archivi appropriati.

Piattaforme Cordova supportate

Cordova 5.0.0+ è completamente supportato, insieme alle piattaforme associate seguenti:

Per controllare le versioni di ogni piattaforma Cordova in uso, è possibile eseguire il comando seguente ed esaminare l'elenco Installed platforms :

    cordova platform ls

Se si esegue una piattaforma Android o iOS precedente precedente e potrebbe essere aperta all'aggiornamento, è possibile farlo facilmente eseguendo i comandi seguenti (omettendo una piattaforma se non è necessaria):

    cordova platform update android
    cordova platform update ios

Introduzione

Nota

Questo articolo contiene riferimenti al termine whitelist, che Microsoft non usa più. Quando il termine verrà rimosso dal software, verrà rimosso anche dall'articolo.

Dopo aver seguito le istruzioni per iniziare per utilizzo generico per la configurazione dell'account CodePush, è possibile avviare CodePush-ifying dell'app Cordova eseguendo il comando seguente dalla directory radice dell'app:

cordova plugin add cordova-plugin-code-push@latest

Dopo aver installato il plug-in CodePush, configurare l'app per usarla tramite la procedura seguente:

  1. Aggiungere le chiavi di distribuzione al file config.xml , assicurandosi di includere la chiave corretta per ogni piattaforma Cordova:
    <platform name="android">
        <preference name="CodePushDeploymentKey" value="YOUR-ANDROID-DEPLOYMENT-KEY" />
    </platform>
    <platform name="ios">
        <preference name="CodePushDeploymentKey" value="YOUR-IOS-DEPLOYMENT-KEY" />
    </platform>

Come promemoria, queste chiavi vengono generate automaticamente quando è stata creata l'app CodePush tramite l'interfaccia della riga di comando. Se è necessario recuperarli, è possibile eseguire appcenter codepush deployment list -a <ownerName>/<appName> --displayKeyse recuperare la chiave per la distribuzione specifica che si vuole usare ( ad esempio Staging, Production).

Importante

È consigliabile creare un'app CodePush separata per iOS e Android, motivo per cui l'esempio precedente dichiara chiavi separate per Android e iOS. Se si sviluppa solo per una singola piattaforma, è sufficiente specificare la chiave di distribuzione per Android o iOS, quindi non è necessario aggiungere l'elemento aggiuntivo <platform> come illustrato in precedenza.

A partire dalla versione 1.10.0 è possibile firmare i bundle di aggiornamento . Per altre informazioni sulla firma del codice, vedere la sezione relativa alla documentazione. Per abilitare la firma del codice per un'applicazione Cordova, è necessario configurare una chiave pubblica per verificare la firma del bundle fornendo un'impostazione preference in config.xml:

    <platform name="android">
        ...
        <preference name="CodePushPublicKey" value="YOUR-PUBLIC-KEY" />
    </platform>
    <platform name="ios">
        ...
        <preference name="CodePushPublicKey" value="YOUR-PUBLIC-KEY" />
    </platform>

È possibile usare la stessa coppia di chiavi privata/pubblica per ogni piattaforma.

  1. Se usi un <access origin="*" /> elemento nel file config.xml , l'app è già autorizzata a comunicare con i server CodePush e puoi ignorare questo passaggio in modo sicuro. In caso contrario, aggiungere gli elementi aggiuntivi <access /> seguenti:
    <access origin="https://codepush.appcenter.ms" />
    <access origin="https://codepush.blob.core.windows.net" />
    <access origin="https://codepushupdates.azureedge.net" />
  1. Per assicurarsi che l'app possa accedere al server CodePush nelle piattaforme conformi a CSP, aggiungere https://codepush.appcenter.ms al Content-Security-Policy meta tag nel index.html file:
    <meta http-equiv="Content-Security-Policy" content="default-src https://codepush.appcenter.ms 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *" />
  1. Infine, verificare di avere già installato il plug-in (la cordova-plugin-whitelist maggior parte delle app). Per verificarlo, eseguire il comando seguente:
    cordova plugin ls

Se cordova-plugin-whitelist è presente nell'elenco, è bene andare. In caso contrario, eseguire il comando seguente per aggiungerlo:

    cordova plugin add cordova-plugin-whitelist

A questo punto è possibile usare il plug-in nel codice dell'applicazione. Per altri dettagli, vedere le applicazioni di esempio e la documentazione dell'API.

Utilizzo plug-in

Con il plug-in CodePush installato e configurato, l'unica cosa lasciata è aggiungere il codice necessario all'app per controllare i criteri seguenti:

  1. Quando (e con quale frequenza) verificare la presenza di un aggiornamento? (e.g. app iniziare, in risposta al clic su un pulsante in una pagina delle impostazioni, periodicamente a un intervallo fisso)
  2. Quando è disponibile un aggiornamento, come presentarlo all'utente finale? Il modo più semplice per eseguire questa operazione consiste nell'eseguire quanto segue nel gestore eventi dell'app deviceready :
codePush.sync();

Se è disponibile un aggiornamento, verrà scaricato automaticamente e installato alla successiva riavvio dell'app (esplicitamente dall'utente finale o dal sistema operativo), che garantisce l'esperienza meno invasiva per gli utenti finali. Se un aggiornamento disponibile è obbligatorio, verrà installato immediatamente, assicurandosi che l'utente finale lo ottenga il prima possibile.

Se vuoi che l'app rilevi gli aggiornamenti più rapidamente, puoi anche scegliere di chiamare sync ogni volta che l'app riprende dallo sfondo aggiungendo il codice seguente (o qualcosa di equivalente) come parte del comportamento di avvio dell'app. È possibile chiamare sync con la frequenza desiderata, quindi quando e dove si chiama dipende dalla preferenza personale.

document.addEventListener("resume", function () {
    codePush.sync();
});

Inoltre, se si desidera visualizzare una finestra di dialogo di conferma dell'aggiornamento (un'installazione attiva), configurare quando viene installato un aggiornamento disponibile (ad esempio forzare un riavvio immediato) o personalizzare l'esperienza di aggiornamento in qualsiasi modo, fare riferimento alle sync informazioni di riferimento sull'API del metodo per informazioni su come modificare questo comportamento predefinito.

Importante

Anche se il contratto per sviluppatori di Apple consente completamente gli aggiornamenti over-the-air di JavaScript e asset (che è ciò che abilita CodePush!), è contro i criteri per un'app per visualizzare una richiesta di aggiornamento. Per questo motivo, è consigliabile che le app distribuite in App Store non consentano di abilitare l'opzione updateDialog quando si chiama sync, mentre Google Play e le app distribuite internamente (ad esempio Enterprise, Fabric, HockeyApp) possono scegliere di abilitarla o personalizzarla.

Rilascio degli aggiornamenti

Dopo aver configurato e distribuito l'app agli utenti e aver apportato alcune modifiche al codice o agli asset, è il momento di rilasciarle immediatamente. Il modo più semplice (e consigliato) per eseguire questa operazione consiste nell'usare il release-cordova comando nell'interfaccia della riga di comando di CodePush, che gestisce la preparazione e il rilascio dell'aggiornamento al server CodePush.

Nota

Prima di iniziare a rilasciare gli aggiornamenti, accedere ad App Center eseguendo il appcenter login comando

Nel formato più semplice, questo comando richiede solo un parametro: il nome del proprietario + "/" + il nome dell'app.

appcenter codepush release-cordova -a <ownerName>/<appName>
appcenter codepush release-cordova -a <ownerName>/MyApp-ios
appcenter codepush release-cordova -a <ownerName>/MyApp-android

Suggerimento

Usando la funzione dell'interfaccia della riga di comando di App Center set-current non è necessario usare il flag -a per specificare l'app a cui viene indirizzato un comando.

Suggerimento

Quando si rilasciano gli aggiornamenti a CodePush, non è necessario aggiornare la versione dell'app nel file config.xml , perché non si modifica affatto la versione binaria. È necessario eseguire l'aggiornamento di questa versione solo quando si aggiorna Cordova o uno dei plug-in, a questo punto, è necessario rilasciare un aggiornamento per gli archivi nativi. CodePush genererà automaticamente una "etichetta" per ogni versione creata ( ad esempio v3) per identificarla all'interno della cronologia delle versioni.

Il release-cordova comando abilita un flusso di lavoro così semplice perché comprende il layout standard di un'app Cordova e quindi può generare l'aggiornamento e sapere esattamente quali file caricare. Inoltre, per supportare strategie di rilascio flessibili, il release-cordova comando espone numerosi parametri facoltativi che consentono di personalizzare la modalità di distribuzione dell'aggiornamento agli utenti finali (ad esempio, con quali versioni binarie sono compatibili? La versione deve essere visualizzata come obbligatoria?).

# Release a mandatory update with a changelog
appcenter codepush release-cordova -a <ownerName>/MyApp-ios -m --description "Modified the header color"

# Release a dev Android build to 1/4 of your end users
appcenter codepush release-cordova -a <ownerName>/MyApp-android --rollout 25

# Release an update that targets users running any 1.1.* binary, as opposed to
# limiting the update to exact version name in the config.xml file
appcenter codepush release-cordova -a <ownerName>/MyApp-android --target-binary-version "~1.1.0"

# Release the update now but mark it as disabled
# so that no users can download it yet
appcenter codepush release-cordova -a <ownerName>/MyApp-ios -x

Il client CodePush supporta gli aggiornamenti differenziali, quindi anche se stai rilasciando il codice dell'app in ogni aggiornamento, gli utenti finali scaricherà solo i file necessari. Il servizio gestisce automaticamente questa operazione in modo che sia possibile concentrarsi sulla creazione di app straordinarie ed è possibile preoccuparsi di ottimizzare i download degli utenti finali.

Per altre informazioni sul funzionamento del release-cordova comando, nonché sui vari parametri esposti, vedere la documentazione dell'interfaccia della riga di comando. Inoltre, se si preferisce gestire l'esecuzione del cordova prepare comando manualmente e quindi, si vuole una soluzione ancora più flessibile di release-cordova, fare riferimento al release comando per altri dettagli.

Se si verificano problemi o si hanno domande/commenti/commenti/ commenti, è possibile inviare un messaggio di posta elettronica a Microsoft o aprire un nuovo problema in questo repository e risponderemo al servizio app. Vedere anche guida e commenti e suggerimenti.

Riferimento API

L'API CodePush viene esposta all'app tramite l'oggetto globale codePush , disponibile dopo che l'evento deviceready viene generato. Questa API espone i metodi di primo livello seguenti:

  • checkForUpdate: chiede al servizio CodePush se la distribuzione dell'app configurata ha un aggiornamento disponibile.
  • getCurrentPackage: recupera i metadati relativi all'aggiornamento attualmente installato, ad esempio descrizione, tempo di installazione, dimensioni.
  • getPendingPackage: recupera i metadati per un aggiornamento (se esistente) scaricato e installato, ma non è ancora stato applicato tramite un riavvio.
  • notifyApplicationReady: notifica al runtime CodePush che un aggiornamento installato è considerato riuscito. Se si sta controllando manualmente la disponibilità e l'installazione degli aggiornamenti (ad esempio, non si usa il metodo di sincronizzazione per gestirlo tutti), questo metodo DEVE essere chiamato. In caso contrario, CodePush considererà l'aggiornamento come non riuscito ed eseguirà il rollback alla versione precedente al riavvio successivo dell'app.
  • restartApplication: riavvia immediatamente l'app. Se è presente un aggiornamento in sospeso, verrà visualizzato immediatamente all'utente finale.
  • sync: consente di verificare la presenza di un aggiornamento, scaricarlo e installarlo, tutto con una singola chiamata. A meno che non sia necessaria un'interfaccia utente o un comportamento personalizzato, è consigliabile che la maggior parte degli sviluppatori usi questo metodo durante l'integrazione di CodePush nelle app.

Inoltre, gli oggetti e le enumerazioni seguenti vengono esposti a livello globale come parte dell'API CodePush:

  • InstallMode: definisce le modalità di installazione disponibili per gli aggiornamenti.
  • LocalPackage: contiene informazioni su un pacchetto installato localmente.
  • RemotePackage: contiene informazioni su un pacchetto di aggiornamento disponibile per il download.
  • SyncStatus: definisce i possibili stati intermedi e di risultato dell'operazione di sincronizzazione .

codePush.checkForUpdate

codePush.checkForUpdate(onSuccess, onError?, deploymentKey?: String);

Esegue una query sul servizio CodePush per verificare se la distribuzione dell'app configurata ha un aggiornamento disponibile. Per impostazione predefinita, userà la chiave di distribuzione configurata nel file config.xml , ma è possibile eseguirne l'override specificando un valore tramite il parametro facoltativo deploymentKey . Ciò può essere utile quando si vuole "reindirizzare" dinamicamente un utente a una distribuzione specifica, ad esempio consentire l'accesso anticipato tramite un uovo di pasqua o un cambio di impostazione utente.

Al termine del controllo dell'aggiornamento, attiverà il onUpdateCheck callback con uno dei due valori possibili:

  1. null se non è disponibile alcun aggiornamento. Ciò si verifica negli scenari seguenti:
    • La distribuzione configurata non contiene alcuna versione, quindi non c'è nulla da aggiornare.
    • La versione più recente all'interno della distribuzione configurata è destinata a una versione binaria diversa rispetto a quella attualmente in esecuzione (precedente o successiva).
    • L'app attualmente in esecuzione ha già la versione più recente della distribuzione configurata, quindi non è necessaria di nuovo la versione.
  2. RemotePackage Istanza che rappresenta un aggiornamento disponibile che può essere controllato e scaricato in un secondo momento.

Parametri:

  • onSuccess: callback richiamato al momento della ricezione di una risposta corretta dal server. Il callback riceve un singolo parametro, descritto in precedenza.
  • onError: callback facoltativo richiamato in caso di errore. Il callback accetta un parametro di errore contenente i dettagli dell'errore.
  • deploymentKey: chiave di distribuzione facoltativa che esegue l'override dell'impostazione config.xml .

Sintassi di esempio:

codePush.checkForUpdate(function (update) {
    if (!update) {
        console.log("The app is up to date.");
    } else {
        console.log("An update is available! Should we download it?");
    }
});

codePush.getCurrentPackage

codePush.getCurrentPackage(onSuccess, onError?);

Recupera i metadati relativi al "pacchetto" attualmente installato (ad esempio, descrizione, ora di installazione). Ciò può essere utile per scenari come la visualizzazione di una finestra di dialogo "Novità?" dopo l'applicazione di un aggiornamento o la verifica dell'eventuale presenza di un aggiornamento in sospeso che è in attesa di essere applicata tramite un curriculum o un riavvio.

Al termine del recupero dell'aggiornamento, attiverà il onSuccess callback con uno dei due valori possibili:

  1. null se l'app esegue attualmente la pagina iniziale HTML dal file binario e non da un aggiornamento codePush. Ciò si verifica negli scenari seguenti:
    • L'utente finale ha installato il file binario dell'app e ha ancora installato un aggiornamento codePush
    • L'utente finale ha installato un aggiornamento del file binario (ad esempio dall'archivio), che ha cancellato i vecchi aggiornamenti codePush e ha restituito la precedenza al file binario.
  2. LocalPackage Istanza che rappresenta i metadati per l'aggiornamento CodePush attualmente in esecuzione.

Parametri:

  • onSuccess: callback richiamato al momento della ricezione dei metadati sull'aggiornamento attualmente in esecuzione. Il callback riceve un singolo parametro, descritto in precedenza.
  • onError: callback facoltativo richiamato in caso di errore. Il callback accetta un parametro di errore contenente i dettagli dell'errore.

Esempio di utilizzo:

codePush.getCurrentPackage(function (update) {
    if (!update) {
        console.log("No updates have been installed");
        return;
    }

    // If the current app "session" represents the first time
    // this update has run, and it had a description provided
    // with it upon release, let's show it to the end user
    if (update.isFirstRun && update.description) {
        // Display a "what's new?" modal
    }
});

codePush.getPendingPackage

codePush.getPendingPackage(onSuccess, onError?);

Ottiene i metadati per l'aggiornamento attualmente in sospeso (se presente). Un aggiornamento viene considerato "in sospeso" se è stato scaricato e installato, ma non è ancora stato applicato tramite un riavvio dell'app. Un aggiornamento potrebbe essere in questo stato solo se InstallMode.ON_NEXT_RESTART o InstallMode.ON_NEXT_RESUME sono stati specificati durante la chiamata sync o LocalPackage.installe l'app non è ancora stata riavviata o ripresa (rispettivamente). Questo metodo può essere utile se si vuole determinare se è presente un aggiornamento in sospeso e quindi chiedere all'utente se desidera riavviarlo immediatamente (tramite codePush.restartApplication) per applicarlo.

Al termine del recupero dell'aggiornamento, attiverà il onSuccess callback con uno dei due valori possibili:

  1. null se l'app non ha attualmente un aggiornamento in sospeso (ad esempio, l'app sta già eseguendo la versione disponibile più recente).
  2. LocalPackage Istanza che rappresenta i metadati per l'aggiornamento CodePush attualmente in sospeso.

Parametri:

  • onSuccess: callback richiamato al momento della ricezione dei metadati sull'aggiornamento attualmente in sospeso. Il callback riceve un singolo parametro, descritto in precedenza.
  • onError: callback facoltativo richiamato in caso di errore. Il callback accetta un parametro di errore contenente i dettagli dell'errore.

Esempio di utilizzo:

codePush.getPendingPackage(function (update) {
    if (update) {
        // An update is currently pending, ask the
        // user if they want to restart
    }
});

codePush.notifyApplicationReady

codePush.notifyApplicationReady(notifySucceeded?, notifyFailed?);

Notifica al runtime CodePush che un aggiornamento appena installato deve essere considerato corretto, quindi non è necessario eseguire il rollback sul lato client automatico. È obbligatorio chiamare questa funzione in un punto qualsiasi nel codice del bundle aggiornato. In caso contrario, al successivo riavvio dell'app, il runtime CodePush presuppone che l'aggiornamento installato non sia riuscito e che venga eseguito il rollback alla versione precedente. Questo comportamento esiste per garantire che gli utenti finali non siano bloccati da un aggiornamento interrotto.

Se si usa la sync funzione e si esegue il controllo degli aggiornamenti all'avvio dell'app, non è necessario chiamare notifyApplicationReady manualmente perché sync lo chiamerà automaticamente. Questo comportamento esiste a causa del presupposto che quando sync viene chiamato nell'app rappresenta una buona approssimazione di un avvio riuscito.

Parametri:

  • notifySucceeded: callback facoltativo richiamato se il plug-in è stato informato correttamente.
  • notifyFailed: callback facoltativo richiamato se si verifica un errore che informa il plug-in.

codePush.restartApplication

codePush.restartApplication();

Riavvia immediatamente l'app. Questo metodo è destinato a scenari avanzati ed è particolarmente utile quando si verificano le condizioni seguenti:

  1. L'app specifica un valore della modalità di installazione pari ON_NEXT_RESTART o ON_NEXT_RESUME quando si chiamano i sync metodi o LocalPackage.install . Questo non applica l'aggiornamento finché l'app non viene riavviata (dall'utente finale o dal sistema operativo) o riprende, quindi l'aggiornamento non verrà visualizzato immediatamente all'utente finale.
  2. Si dispone di un evento utente specifico dell'app (ad esempio, l'utente finale ha tornando alla home route dell'app) che consente di applicare l'aggiornamento in modo non invadente e potenzialmente ottiene l'aggiornamento davanti all'utente finale prima dell'attesa fino al successivo riavvio o ripresa.

codePush.sync

codePush.sync(syncCallback?, syncOptions?, downloadProgress?, syncErrback?);

Sincronizza il codice e le immagini dell'app con la versione più recente con la distribuzione configurata. A differenza del checkForUpdate metodo , che verifica la presenza di un aggiornamento e consente di controllare le operazioni da eseguire successivamente, sync gestisce automaticamente il controllo degli aggiornamenti, l'esperienza di download e installazione.

Questo metodo fornisce supporto per due diverse "modalità" (ma personalizzabili) per abilitare facilmente le app con requisiti diversi:

  1. Modalità invisibile all'utente (comportamento predefinito) che scarica automaticamente gli aggiornamenti disponibili e li applica alla successiva riavvio dell'app(ad esempio, il sistema operativo o l'utente finale lo ha ucciso o il dispositivo è stato riavviato). In questo modo, l'intera esperienza di aggiornamento è "invisibile all'utente finale", poiché non visualizza alcuna richiesta di aggiornamento o riavvii dell'app "sintetica".
  2. Modalità attiva, che quando è disponibile un aggiornamento, richiede all'utente finale l'autorizzazione prima di scaricarla e quindi applica immediatamente l'aggiornamento. Se un aggiornamento è stato rilasciato usando il flag obbligatorio, l'utente finale riceverà comunque una notifica sull'aggiornamento, ma non avrebbe la scelta di ignorarla.

Esempio di utilizzo:

// Fully silent update that keeps the app in
// sync with the server, without ever
// interrupting the end user
codePush.sync();

// Active update that lets the end user know
// about each update, and displays it to them
// immediately after downloading it
codePush.sync(null, { updateDialog: true, installMode: InstallMode.IMMEDIATE });

Suggerimento

Se si desidera decidere se controllare o scaricare un aggiornamento disponibile in base al livello di batteria del dispositivo dell'utente finale, alle condizioni di rete e così via, eseguire il wrapping della chiamata per la sincronizzazione in una condizione che garantisce di chiamarlo solo quando necessario.

Mentre il metodo di sincronizzazione tenta di semplificare l'esecuzione di aggiornamenti invisibile all'utente e attivi con una configurazione piccola, accetta i parametri facoltativi seguenti che consentono di personalizzare numerosi aspetti del comportamento predefinito indicato in precedenza:

  • syncCallback: chiamato quando il processo di sincronizzazione passa da una fase a un'altra nel processo di aggiornamento complessivo. Il metodo viene chiamato con un codice di stato che rappresenta lo stato corrente e può essere uno qualsiasi dei SyncStatus valori.
  • syncOptions: parametro facoltativo SyncOptions che configura il comportamento dell'operazione di sincronizzazione.
  • downloadProgress: chiamato periodicamente quando viene scaricato un aggiornamento disponibile dal server CodePush. Il metodo viene chiamato con un DownloadProgress oggetto , che contiene le due proprietà seguenti:
    • totalBytes (Number) - Numero totale di byte che si prevede di ricevere per questo aggiornamento (ad esempio, la dimensione del set di file modificati rispetto alla versione precedente).
    • receivedBytes (Numero): numero di byte scaricati finora, che possono essere usati per tenere traccia dello stato di avanzamento del download.
  • syncErrback: chiamato quando si verifica un errore in uno dei passaggi interni di sincronizzazione. Il metodo viene chiamato con un oggetto javascript Error standard come primo argomento.

SyncOptions

Mentre il sync metodo tenta di semplificare l'esecuzione di aggiornamenti invisibile all'utente e attivi con una configurazione piccola, accetta un oggetto "opzioni" che consente di personalizzare numerosi aspetti del comportamento predefinito indicato in precedenza:

  • deploymentKey (String): specifica la chiave di distribuzione su cui eseguire una query per un aggiornamento. Per impostazione predefinita, questo valore è derivato dal file config.xml , ma questa opzione consente di eseguirne l'override dal lato script se è necessario usare in modo dinamico una distribuzione diversa per una chiamata specifica a sync.
  • installMode (InstallMode): specifica quando si desidera installare gli aggiornamenti facoltativi (ad esempio quelli che non sono contrassegnati come obbligatori). Il valore predefinito è InstallMode.ON_NEXT_RESTART. Fare riferimento alle InstallMode enumerazioni per una descrizione delle opzioni disponibili e delle relative operazioni.
  • mandatoryInstallMode (InstallMode): specifica quando si desidera installare gli aggiornamenti contrassegnati come obbligatori. Il valore predefinito è InstallMode.IMMEDIATE. Fare riferimento alle InstallMode enumerazioni per una descrizione delle opzioni disponibili e delle relative operazioni.
  • minimumBackgroundDuration (numero): specifica il numero minimo di secondi per l'app in background prima di riavviare l'app. Questa proprietà si applica solo agli aggiornamenti installati tramite InstallMode.ON_NEXT_RESUMEe possono essere utili per ottenere prima l'aggiornamento davanti agli utenti finali, senza essere troppo invadenti. L'impostazione predefinita è 0, che applica l'aggiornamento immediatamente dopo un curriculum, purché sia stato in background.
  • ignoreFailedUpdates (booleano): specifica se un aggiornamento disponibile deve essere ignorato se è stato installato in precedenza ed è stato eseguito il rollback nel client (perché notifyApplicationReady non è stato chiamato correttamente). Il valore predefinito è true.
  • updateDialog (UpdateDialogOptions): oggetto "opzioni" usato per determinare se all'utente finale deve essere visualizzata una finestra di dialogo di conferma quando è disponibile un aggiornamento e, in tal caso, quali stringhe usare. L'impostazione predefinita è null, che disabilita la finestra di dialogo. L'impostazione di questo valore su qualsiasi true valore consentirà la finestra di dialogo con le stringhe predefinite e il passaggio di un oggetto a questo parametro consente di abilitare la finestra di dialogo e di eseguire l'override di una o più stringhe predefinite.

L'elenco seguente rappresenta le opzioni disponibili e le relative impostazioni predefinite:

  • appendReleaseDescription (booleano): indica se si vuole aggiungere la descrizione di una versione disponibile al messaggio di notifica visualizzato all'utente finale. Il valore predefinito è false.
  • descriptionPrefix (String) - Indica la stringa con cui si vuole anteporre la descrizione della versione, se presente, quando viene visualizzata la notifica di aggiornamento all'utente finale. Il valore predefinito è " Description: ".
  • mandatoryContinueButtonLabel (String): il testo da usare per il pulsante che l'utente finale deve premere per installare un aggiornamento obbligatorio. Il valore predefinito è "Continue".
  • mandatoryUpdateMessage (String) - Testo usato come corpo di una notifica di aggiornamento, quando l'aggiornamento viene specificato come obbligatorio. Il valore predefinito è "An update is available that must be installed.".
  • optionalIgnoreButtonLabel (String): il testo da usare per il pulsante che l'utente finale può premere per ignorare un aggiornamento facoltativo disponibile. Il valore predefinito è "Ignore".
  • optionalInstallButtonLabel (String): il testo da usare per il pulsante che l'utente finale può premere per installare un aggiornamento facoltativo. Il valore predefinito è "Install".
  • optionalUpdateMessage (String): testo usato come corpo di una notifica di aggiornamento, quando l'aggiornamento è facoltativo. Il valore predefinito è "An update is available. Would you like to install it?". *- updateTitle (String) - Testo usato come intestazione di una notifica di aggiornamento visualizzata all'utente finale. Il valore predefinito è "Update available".

Esempio di utilizzo:

// Download the update silently, but install it on
// the next resume, as long as at least 5 minutes
// has passed since the app was put into the background.
codePush.sync(null, { installMode: InstallMode.ON_NEXT_RESUME, minimumBackgroundDuration: 60 * 5 });

// Download the update silently, and install optional updates
// on the next restart, but install mandatory updates on the next resume.
codePush.sync(null, { mandatoryInstallMode: InstallMode.ON_NEXT_RESUME });

// Changing the title displayed in the
// confirmation dialog of an "active" update
codePush.sync(null, { updateDialog: { title: "An update is available!" } });

// Displaying an update prompt that includes the
// description for the CodePush release
codePush.sync(null, {
   updateDialog: {
    appendReleaseDescription: true,
    descriptionPrefix: "\n\nChange log:\n"
   },
   installMode: InstallMode.IMMEDIATE
});

// Silently check for the update, but
// display a custom downloading UI
// via the SyncStatus and DownloadProgress callbacks
codePush.sync(syncStatus, null, downloadProgress);

function syncStatus(status) {
    switch (status) {
        case SyncStatus.DOWNLOADING_PACKAGE:
            // Show "downloading" modal
            break;
        case SyncStatus.INSTALLING_UPDATE:
            // Hide "downloading" modal
            break;
    }
}

function downloadProgress(downloadProgress) {
    if (downloadProgress) {
    	// Update "downloading" modal with current download %
        //console.log("Downloading " + downloadProgress.receivedBytes + " of " + downloadProgress.totalBytes);
    }
}

Il sync metodo può essere chiamato ovunque si voglia verificare la presenza di un aggiornamento. Potrebbe trovarsi nel deviceready gestore eventi, nell'evento click di un pulsante, nel callback di un timer periodico o in qualsiasi altro modo per le proprie esigenze. Come il checkForUpdate metodo , eseguirà la richiesta di rete per verificare la presenza di un aggiornamento in background, quindi non influisce sulla velocità di risposta del thread dell'interfaccia utente o del thread JavaScript.

Oggetti pacchetto

I checkForUpdate metodi e getCurrentPackage richiamano callback di esito positivo, che, quando attivato, forniscono l'accesso agli oggetti "package". Il pacchetto rappresenta l'aggiornamento del codice e i metadati aggiuntivi (ad esempio, descrizione obbligatoria?). L'API CodePush ha la distinzione tra i tipi di pacchetti seguenti:

  1. LocalPackage: rappresenta un aggiornamento scaricato già in esecuzione oppure è stato installato ed è in attesa di un riavvio dell'app.
  2. RemotePackage: rappresenta un aggiornamento disponibile nel server CodePush che non è ancora stato scaricato.

LocalPackage

Contiene informazioni dettagliate su un aggiornamento scaricato in locale o già installato. È possibile ottenere un riferimento a un'istanza di questo oggetto chiamando il codePush.getCurrentPackage metodo o come valore fornito al callback dell'esito positivo del RemotePackage.download metodo .

Proprietà
  • appVersion: la versione nativa dell'applicazione per cui è destinato questo aggiornamento del pacchetto. (String)
  • deploymentKey: chiave di distribuzione del pacchetto. (String)
  • description: descrizione dell'aggiornamento. Questo è lo stesso valore specificato nell'interfaccia della riga di comando quando è stato rilasciato l'aggiornamento. (String)
  • failedInstall: indica se questo aggiornamento è stato installato in precedenza ma è stato eseguito il rollback. Il sync metodo ignorerà automaticamente gli aggiornamenti che in precedenza non sono riusciti, pertanto è sufficiente preoccuparsi di questa proprietà se si usa checkForUpdate. (Boolean)
  • isFirstRun: flag che indica se l'esecuzione dell'applicazione corrente è la prima dopo l'applicazione del pacchetto. (Boolean)
  • isMandatory: indica se l'aggiornamento è considerato obbligatorio. Questo è il valore specificato nell'interfaccia della riga di comando quando è stato rilasciato l'aggiornamento. (Boolean)
  • label: etichetta interna assegnata automaticamente all'aggiornamento dal server CodePush, ad esempio v5. Questo valore identifica in modo univoco l'aggiornamento all'interno della distribuzione. (String)
  • packageHash: valore hash SHA dell'aggiornamento. (String)
  • packageSize: dimensioni del codice contenuto nell'aggiornamento, in byte. (Numero)
Metodi
  • install(installSuccess, installError, installOptions): installa questo pacchetto nell'applicazione. Il comportamento di installazione dipende dall'oggetto fornito installOptions. Per impostazione predefinita, il pacchetto di aggiornamento viene installato automaticamente e l'applicazione viene ricaricata con il nuovo contenuto all'avvio dell'applicazione successiva. Alla prima esecuzione dopo l'aggiornamento, l'applicazione attenderà una codePush.notifyApplicationReady() chiamata. Una volta effettuata questa chiamata, l'operazione di installazione viene considerata riuscita. In caso contrario, l'operazione di installazione verrà contrassegnata come non riuscita e l'applicazione viene ripristinata alla versione precedente all'esecuzione successiva.
InstallOptions

Interfaccia che definisce diverse opzioni per personalizzare il comportamento dell'operazione di installazione.

  • installMode: usato per specificare InstallMode usato per l'operazione di installazione. Il valore predefinito è InstallMode.ON_NEXT_RESTART.
  • mandatoryInstallMode: usato per specificare installMode usato per l'operazione di installazione se il pacchetto è obbligatorio. Il valore predefinito è InstallMode.IMMEDIATE.
  • minimumBackgroundDuration: se installMode è InstallMode.ON_NEXT_RESUME, usato per specificare la quantità di tempo in cui l'app deve trovarsi in background prima dell'installazione dell'aggiornamento quando viene ripresa. Il valore predefinito è 0.

Esempio di utilizzo:

// App version 1 (current version)

var onError = function (error) {
    console.log("An error occurred. " + error);
};

var onInstallSuccess = function () {
    console.log("Installation succeeded.");
};

var onPackageDownloaded = function (localPackage) {
    // Install regular updates after someone navigates away from the app for more than 2 minutes
    // Install mandatory updates after someone restarts the app
    localPackage.install(onInstallSuccess, onError, { installMode: InstallMode.ON_NEXT_RESUME, minimumBackgroundDuration: 120, mandatoryInstallMode: InstallMode.ON_NEXT_RESTART });
};

var onUpdateCheck = function (remotePackage) {
    if (!remotePackage) {
        console.log("The application is up to date.");
    } else {
        // The hash of each previously reverted package is stored for later use.
        // This way, we avoid going into an infinite bad update/revert loop.
        if (!remotePackage.failedInstall) {
            console.log("A CodePush update is available. Package hash: " + remotePackage.packageHash);
            remotePackage.download(onPackageDownloaded, onError);
        } else {
            console.log("The available update was attempted before and failed.");
        }
    }
};

window.codePush.checkForUpdate(onUpdateCheck, onError);

//------------------------------------------------
// App version 2 (updated version)
var app = {
    onDeviceReady: function () {
        // Calling this function is required during the first application run after an update.
        // If not called, the application will be reverted to the previous version.
        window.codePush.notifyApplicationReady();
        // ...
    }
}

Per un esempio su come si è protetti da un aggiornamento non valido, vedere la documentazione notifyApplicationReady().

RemotePackage

Contiene informazioni dettagliate su un aggiornamento disponibile per il download dal server CodePush. Si ottiene un riferimento a un'istanza di questo oggetto chiamando il codePush.checkForUpdate metodo quando è disponibile un aggiornamento. Se si usa l'API di sincronizzazione, non è necessario preoccuparsi di RemotePackage, perché gestirà automaticamente il processo di download e installazione.

Proprietà

RemotePackage eredita tutte le stesse proprietà LocalPackagedi , ma ne include uno aggiuntivo:

  • downloadUrl: URL in cui è disponibile il pacchetto per il download. Questa proprietà è necessaria solo per l'utilizzo avanzato, poiché il download metodo gestirà automaticamente l'acquisizione degli aggiornamenti. (String)
Metodi
  • abortDownload(abortSuccess, abortError): interrompe la sessione di download corrente, se presente.
  • download(downloadSuccess, downloadError, downloadProgress): scarica l'aggiornamento del pacchetto dal servizio CodePush. Il downloadSuccess callback viene richiamato con un argomento LocalPackage , che rappresenta il pacchetto scaricato. Il callback facoltativo viene richiamato downloadProgress più volte durante lo stato di avanzamento del download con un DownloadProgress solo parametro.
DownloadProgress

Definisce il formato dell'oggetto DownloadProgress, utilizzato per inviare notifiche di aggiornamento periodiche sullo stato di avanzamento del download dell'aggiornamento.

Proprietà
  • totalBytes: dimensioni in byte del pacchetto di aggiornamento di download. (Numero)
  • receivedBytes: numero di byte già scaricati. (Numero)

Esempio di utilizzo:

var onError = function (error) {
    console.log("An error occurred. " + error);
};

var onPackageDownloaded = function (localPackage) {
    console.log("Package downloaded at: " + localPackage.localPath);
    // you can now update your application to the downloaded version by calling localPackage.install()
};

var onProgress = function (downloadProgress) {
    console.log("Downloading " + downloadProgress.receivedBytes + " of " + downloadProgress.totalBytes + " bytes.");
};

var onUpdateCheck = function (remotePackage) {
    if (!remotePackage) {
        console.log("The application is up to date.");
    } else {
        console.log("A CodePush update is available. Package hash: " + remotePackage.packageHash);
        remotePackage.download(onPackageDownloaded, onError, onProgress);
    }
};

window.codePush.checkForUpdate(onUpdateCheck, onError);

Enumerazioni

L'API CodePush include gli oggetti "enum" seguenti che possono essere usati per personalizzare l'esperienza di aggiornamento e sono disponibili a livello globale all'esterno dell'oggetto window :

InstallMode

Questa enumerazione specificata quando si desidera che un aggiornamento installato venga effettivamente applicato e può essere passato ai sync metodi o LocalPackage.install . Include i valori seguenti:

  • IMMEDIATE: l'aggiornamento verrà applicato immediatamente all'applicazione in esecuzione. L'applicazione verrà ricaricata immediatamente con il nuovo contenuto.
  • ON_NEXT_RESTART: indica che si vuole installare l'aggiornamento, ma non riavviare forzatamente l'app. Quando l'app viene riavviata "naturalmente" (a causa del sistema operativo o dell'utente finale che lo uccide), l'aggiornamento verrà prelevato senza problemi. Questo valore è appropriato quando si eseguono aggiornamenti invisibile all'utente invisibile all'utente, poiché è probabile che l'utente finale abbia riavviato improvvisamente l'app da nessuna parte, poiché non si sarebbe reso conto che un aggiornamento è stato anche scaricato. Questa è la modalità predefinita usata per entrambi i sync metodi e LocalPackage.install .

Per un esempio su come si è protetti da un aggiornamento non valido, vedere la documentazione notifyApplicationReady().

RemotePackage

Contiene informazioni dettagliate su un aggiornamento disponibile per il download dal server CodePush. Si ottiene un riferimento a un'istanza di questo oggetto chiamando il codePush.checkForUpdate metodo quando è disponibile un aggiornamento. Se si usa l'API di sincronizzazione, non è necessario preoccuparsi di RemotePackage, perché gestirà automaticamente il processo di download e installazione.

Proprietà

RemotePackage eredita tutte le stesse proprietà LocalPackagedi , ma ne include uno aggiuntivo:

  • downloadUrl: URL in cui è disponibile il pacchetto per il download. Questa proprietà è necessaria solo per l'utilizzo avanzato, poiché il download metodo gestirà automaticamente l'acquisizione degli aggiornamenti. (String)
Metodi
  • abortDownload(abortSuccess, abortError): interrompe la sessione di download corrente, se presente.
  • download(downloadSuccess, downloadError, downloadProgress): scarica l'aggiornamento del pacchetto dal servizio CodePush. Il downloadSuccess callback viene richiamato con un argomento LocalPackage , che rappresenta il pacchetto scaricato. Il callback facoltativo viene richiamato downloadProgress più volte durante lo stato di avanzamento del download con un DownloadProgress solo parametro.
DownloadProgress

Definisce il formato dell'oggetto DownloadProgress, utilizzato per inviare notifiche di aggiornamento periodiche sullo stato di avanzamento del download dell'aggiornamento.

# Proprietà
  • totalBytes: dimensioni in byte del pacchetto di aggiornamento di download. (Numero)
  • receivedBytes: numero di byte già scaricati. (Numero)

Esempio di utilizzo:

var onError = function (error) {
    console.log("An error occurred. " + error);
};

var onPackageDownloaded = function (localPackage) {
    console.log("Package downloaded at: " + localPackage.localPath);
    // you can now update your application to the downloaded version by calling localPackage.install()
};

var onProgress = function (downloadProgress) {
    console.log("Downloading " + downloadProgress.receivedBytes + " of " + downloadProgress.totalBytes + " bytes.");
};

var onUpdateCheck = function (remotePackage) {
    if (!remotePackage) {
        console.log("The application is up to date.");
    } else {
        console.log("A CodePush update is available. Package hash: " + remotePackage.packageHash);
        remotePackage.download(onPackageDownloaded, onError, onProgress);
    }
};

window.codePush.checkForUpdate(onUpdateCheck, onError);

Enumerazioni

L'API CodePush include gli oggetti "enum" seguenti che possono essere usati per personalizzare l'esperienza di aggiornamento e sono disponibili a livello globale all'esterno dell'oggetto window :

InstallMode

Questa enumerazione specificata quando si desidera che un aggiornamento installato venga effettivamente applicato e può essere passato ai sync metodi o LocalPackage.install . Include i valori seguenti:

  • IMMEDIATE: l'aggiornamento verrà applicato immediatamente all'applicazione in esecuzione. L'applicazione verrà ricaricata immediatamente con il nuovo contenuto.
  • ON_NEXT_RESTART: indica che si vuole installare l'aggiornamento, ma non riavviare forzatamente l'app. Quando l'app viene riavviata "naturalmente" (a causa del sistema operativo o dell'utente finale che lo uccide), l'aggiornamento verrà prelevato senza problemi. Questo valore è appropriato quando si eseguono aggiornamenti invisibile all'utente invisibile all'utente, poiché è probabile che l'utente finale abbia riavviato improvvisamente l'app da nessuna parte, poiché non si sarebbe reso conto che un aggiornamento è stato anche scaricato. Questa è la modalità predefinita usata per entrambi i sync metodi e LocalPackage.install .
  • ON_NEXT_RESUME: indica che si vuole installare l'aggiornamento, ma non si vuole riavviare l'app fino alla successiva ripresa dall'utente finale dallo sfondo. In questo modo, non si interrompe la sessione corrente, ma è possibile ottenere l'aggiornamento davanti a loro prima di dover attendere il successivo riavvio naturale. Questo valore è appropriato per le installazioni invisibile all'utente che possono essere applicate al curriculum in modo non invasivo.

SyncStatus

Definisce gli stati possibili dell'operazione di sincronizzazione . Esistono due categorie di stati: intermedio e risultato (finale). Gli stati intermedi rappresentano gli stati di avanzamento dell'operazione di sincronizzazione e non sono finali. Gli stati dei risultati rappresentano gli stati finali dell'operazione di sincronizzazione. Ogni operazione di sincronizzazione termina con un solo stato di risultato, ma può avere zero o più stati intermedi.

  • UP_TO_DATE: l'app è completamente aggiornata con la distribuzione configurata.
  • UPDATE_INSTALLED: un aggiornamento disponibile è stato installato e verrà eseguito immediatamente dopo la restituzione della funzione di callback o la successiva ripresa/riavvio dell'app, a seconda dell'oggetto InstallMode specificato in SyncOptions.
  • UPDATE_IGNORED: l'app ha un aggiornamento facoltativo, che l'utente finale ha scelto di ignorare. (Questo è applicabile solo quando updateDialog viene usato )
  • ERRORE: si è verificato un errore durante l'operazione sync . Potrebbe trattarsi di un errore durante la comunicazione con il server, il download o il decompressione dell'aggiornamento. I log della console devono contenere altre informazioni su ciò che è successo. In questo caso non è stato applicato alcun aggiornamento.
  • IN_PROGRESS: un'altra sincronizzazione è già in esecuzione, quindi questo tentativo di sincronizzazione è stato interrotto.
  • CHECKING_FOR_UPDATE: viene eseguita una query sul server CodePush per un aggiornamento.
  • AWAITING_USER_ACTION: è disponibile un aggiornamento e viene visualizzata una finestra di dialogo di conferma all'utente finale. (Questo è applicabile solo quando updateDialog viene usato )
  • DOWNLOADING_PACKAGE: un aggiornamento disponibile viene scaricato dal server CodePush.
  • INSTALLING_UPDATE: è stato scaricato un aggiornamento disponibile che sta per essere installato.

Compilazione PhoneGap

Questo plug-in è compatibile con PhoneGap Build e supporta la creazione di build android e iOS predefinite. Tuttavia, per consentire a CodePush di calcolare l'hash del contenuto binario in Android, PhoneGap Build deve usare Gradle per compilare l'app, che non è il comportamento predefinito (usa Ant). Per risolvere questo problema, aggiungere l'elemento seguente al file di config.xml del progetto come figlio dell'elemento <platform name="android"> :

<preference name="android-build-tool" value="gradle" />

App di esempio

La community di Cordova ha creato alcune straordinarie app open source che possono essere usate come esempi per gli sviluppatori che iniziano a usare. L'elenco seguente è costituito dalle app Cordova OSS che usano anche CodePush e possono essere usate per vedere in che modo altri utenti usano il servizio:

Nota

Se hai sviluppato un'app Cordova usando CodePush, è open source, comunicaci. Ci piacerebbe aggiungerlo a questo elenco!