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 prendere in considerazione la migrazione.

Altre informazioni sulle sequenze temporali di supporto e sulle alternative.

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 store in cui si sta pubblicando.

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

Per garantire che gli utenti finali dispongano sempre di una versione funzionante dell'app, il plug-in CodePush mantiene una copia dell'aggiornamento precedente, in modo che, in caso di push accidentale di 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à l'blocco degli utenti prima di poter eseguire il rollback sul server. È un win-win-win!

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 attualmente 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

Guida introduttiva

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 " introduttive" 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 diconfig.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 specificando 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 ed è possibile ignorare in modo sicuro questo passaggio. 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-Policymeta 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 che il cordova-plugin-whitelist plug-in sia già installato (la maggior parte delle app). Per verificarlo, eseguire il comando seguente:
    cordova plugin ls

Se cordova-plugin-whitelist è presente nell'elenco, è consigliabile 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 del 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 a fare 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 (in modo esplicito dall'utente finale o dal sistema operativo), che garantisce l'esperienza meno invasiva per gli utenti finali. Se è obbligatorio un aggiornamento disponibile, 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 lo chiami 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 sulle API del metodo per informazioni su come modificare questo comportamento predefinito.

Importante

Anche se il contratto per sviluppatori di Apple consente completamente gli aggiornamenti in modalità over-the-air di JavaScript e asset (che è ciò che consente a CodePush!), è in base ai criteri per un'app per visualizzare una richiesta di aggiornamento. Per questo motivo, è consigliabile che le app distribuite App Store non abilitino 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 di Aggiornamenti

Dopo aver configurato e distribuito l'app agli utenti e aver apportato alcune modifiche al codice o agli asset, è possibile 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 nel 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 rilascia gli aggiornamenti a CodePush, non devi urtare la versione dell'app nel file config.xml , perché non modifichi affatto la versione binaria. È sufficiente aggiornare questa versione 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é riconosce 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 quali versioni binarie sono compatibili con esso? 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 si rilascia il codice dell'app in ogni aggiornamento, gli utenti finali scaricherà solo i file necessari. Il servizio gestisce automaticamente questa funzionalità in modo da potersi concentrare sulla creazione di app eccezionali ed è possibile preoccuparsi dell'ottimizzazione dei download degli utenti finali.

Per altre informazioni sul funzionamento del release-cordova comando e 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 e suggerimenti, è possibile inviare un messaggio di posta elettronica o aprire un nuovo problema in questo repository e risponderemo a ASAP! Vedere anche guida e feedback.

Informazioni di riferimento sulle API

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

  • checkForUpdate: chiede al servizio CodePush se la distribuzione dell'app configurata dispone di 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 presente) scaricati e installati, ma non ancora applicati tramite un riavvio.
  • notifyApplicationReady: notifica al runtime CodePush che un aggiornamento installato è considerato riuscito. Se si esegue manualmente il controllo 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 e eseguirà il rollback alla versione precedente al successivo riavvio 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 in locale.
  • 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 dispone di un aggiornamento disponibile. Per impostazione predefinita, userà la chiave di distribuzione configurata nel file config.xml , ma è possibile eseguire l'override di tale valore 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 commutatore di impostazione utente.

Al termine del controllo di aggiornamento, il callback verrà attivato onUpdateCheck con uno dei due valori possibili:

  1. null se non è disponibile alcun aggiornamento. Ciò si verifica negli scenari seguenti:
    • La distribuzione configurata non contiene versioni, quindi non è possibile aggiornare nulla.
    • 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 dalla distribuzione configurata, quindi non necessita nuovamente della 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 diconfig.xml .

Esempio di utilizzo:

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. Questo può essere utile per gli scenari come la visualizzazione di una finestra di dialogo "novità?" dopo l'applicazione di un aggiornamento o il controllo se è presente un aggiornamento in sospeso che è in attesa di essere applicato tramite una ripresa o un riavvio.

Al termine del recupero dell'aggiornamento onSuccess , il callback verrà attivato 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 eliminato gli aggiornamenti codePush precedenti e ha dato 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 relativi all'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 è stato ancora applicato tramite un riavvio dell'app. Un aggiornamento potrebbe essere in questo stato solo se InstallMode.ON_NEXT_RESTART o sono stati specificati durante la chiamata sync o InstallMode.ON_NEXT_RESUMELocalPackage.install, e 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 richiedere all'utente di riavviarlo immediatamente (tramite codePush.restartApplication) per applicarlo.

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

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

Parametri

  • onSuccess: callback richiamato dopo aver ricevuto i metadati relativi all'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 deve essere considerato corretto un aggiornamento appena installato, quindi un rollback lato client automatico non è necessario. È obbligatorio chiamare questa funzione nel codice del bundle aggiornato. In caso contrario, quando l'app viene riavviata, il runtime CodePush presuppone che l'aggiornamento installato non sia riuscito e 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 funzione e si esegue il sync controllo dell'aggiornamento all'avvio dell'app, non è necessario chiamare notifyApplicationReady manualmente perché sync lo chiamerà. Questo comportamento esiste a causa del presupposto che quando sync viene chiamato nell'app rappresenta un'approssimazione ottimale di un'avvio riuscito.

Parametri

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

codePush.restartApplication

codePush.restartApplication();

Riavvia immediatamente l'app. Questo metodo è per scenari avanzati ed è principalmente utile quando le condizioni seguenti sono vere:

  1. L'app specifica un valore della modalità di installazione di 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 è tornato alla home route dell'app) che consente di applicare l'aggiornamento in modo non invasivo e potenzialmente ottiene l'aggiornamento davanti all'utente finale prima di attendere il riavvio successivo o riprendere.

codePush.sync

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

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

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

  1. Modalità invisibileall'utente in modalità automatica(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 visualizzano alcuna richiesta di aggiornamento o il riavvio 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 vuole 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 chiamarla solo quando si desidera.

Anche se il metodo di sincronizzazione tenta di semplificare l'esecuzione degli aggiornamenti invisibile 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 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 devono essere ricevuti per questo aggiornamento (ad esempio le dimensioni del set di file che sono state modificate dalla versione precedente).
    • receivedBytes(Number) - 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

Anche se il sync metodo tenta di semplificare l'esecuzione degli aggiornamenti invisibile 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 che si vuole eseguire una query su un aggiornamento. Per impostazione predefinita, questo valore deriva dal file config.xml , ma questa opzione consente di eseguirne l'override dal lato script se è necessario usare dinamicamente 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 all'enumerazione InstallMode per una descrizione delle opzioni disponibili e delle operazioni eseguite.
  • mandatoryInstallMode(InstallMode): specifica quando si desidera installare gli aggiornamenti contrassegnati come obbligatori. Il valore predefinito è InstallMode.IMMEDIATE. Fare riferimento all'enumerazione InstallMode per una descrizione delle opzioni disponibili e delle operazioni eseguite.
  • minimumBackgroundDuration(Number) - Specifica il numero minimo di secondi per l'app in background prima di riavviare l'app. Questa proprietà si applica solo agli aggiornamenti installati usando InstallMode.ON_NEXT_RESUMEe può essere utile per ottenere l'aggiornamento prima degli utenti finali, senza essere troppo intrusivi. Il valore predefinito è 0, che applica l'aggiornamento immediatamente dopo una ripresa, tuttavia è stato in background.
  • ignoreFailedUpdates(Boolean): specifica se un aggiornamento disponibile deve essere ignorato se è stato installato e eseguito il rollback precedente nel client (perché notifyApplicationReady non è stato chiamato correttamente). Il valore predefinito è true.
  • updateDialog(UpdateDialogOptions): oggetto "options" usato per determinare se deve essere visualizzata una finestra di dialogo di conferma all'utente finale quando è disponibile un aggiornamento e, in tal caso, quali stringhe usare. Impostazione predefinita su null, che disabilita la finestra di dialogo. Impostando questo valore su qualsiasi true valore, la finestra di dialogo con le stringhe predefinite e passando 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(Boolean): 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 assegnare il prefisso della descrizione della versione con, 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 l'utente finale deve premere per installare un aggiornamento obbligatorio. Il valore predefinito è "Continue".
  • mandatoryUpdateMessage(String) : il 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.".
  • facoltativoIgnoreButtonLabel(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) : il 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 desidera verificare la presenza di un aggiornamento. Ciò potrebbe essere nel gestore eventi, l'evento devicereadyclick di un pulsante, nel callback di un timer periodico o qualsiasi altra cosa abbia senso 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 sul thread dell'interfaccia utente o sulla velocità di risposta del thread JavaScript.

Oggetti pacchetto

I checkForUpdate metodi e getCurrentPackage richiamano i callback di esito positivo, che, quando attivato, forniscono l'accesso agli oggetti "package". Il pacchetto rappresenta l'aggiornamento del codice e tutti i metadati aggiuntivi (ad esempio, descrizione, obbligatorio?). 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 i dettagli relativi a 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 di esito positivo del RemotePackage.download metodo.

Proprietà
  • appVersion: la versione nativa dell'applicazione per questo aggiornamento del pacchetto è destinata. (Stringa)
  • deploymentKey: chiave di distribuzione del pacchetto. (Stringa)
  • descrizione: Descrizione dell'aggiornamento. Questo è lo stesso valore specificato nell'interfaccia della riga di comando quando è stato rilasciato l'aggiornamento. (Stringa)
  • failedInstall: indica se questo aggiornamento è stato installato in precedenza, ma è stato eseguito il rollback. Il sync metodo ignora automaticamente gli aggiornamenti che in precedenza non sono riusciti, quindi è necessario preoccuparsi solo di questa proprietà se si usa checkForUpdate. (booleano)
  • isFirstRun: flag che indica se l'esecuzione dell'applicazione corrente è la prima dopo l'applicazione applicata. (booleano)
  • isMandatory: indica se l'aggiornamento è considerato obbligatorio. Questo è il valore specificato nell'interfaccia della riga di comando quando è stato rilasciato l'aggiornamento. (booleano)
  • etichetta: etichetta interna assegnata automaticamente all'aggiornamento dal server CodePush, ad esempio v5. Questo valore identifica in modo univoco l'aggiornamento all'interno della distribuzione. (Stringa)
  • packageHash: valore hash SHA dell'aggiornamento. (Stringa)
  • packageSize: dimensioni del codice contenute nell'aggiornamento, in byte. (Numero)
Metodi
  • install(installSuccess, installError, installOptions): installa questo pacchetto nell'applicazione. Il comportamento di installazione dipende dall'oggetto specificato installOptions. Per impostazione predefinita, il pacchetto di aggiornamento viene installato in modo invisibile all'utente e l'applicazione viene ricaricata con il nuovo contenuto nell'avvio dell'applicazione successiva. Nella prima esecuzione dopo l'aggiornamento, l'applicazione attenderà una codePush.notifyApplicationReady() chiamata. Una volta effettuata questa chiamata, l'operazione di installazione viene considerata un esito positivo. In caso contrario, l'operazione di installazione verrà contrassegnata come non riuscita e l'applicazione viene ripristinata alla versione precedente dell'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 necessario per l'app in background prima dell'installazione dell'aggiornamento quando viene ripreso. 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 di 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, poiché gestirà automaticamente il processo di download e installazione.

Proprietà

L'oggetto RemotePackage eredita tutte le stesse proprietà dell'oggetto LocalPackage, ma 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. (Stringa)
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 più volte durante lo stato di avanzamento downloadProgress del download con un DownloadProgress parametro.
DownloadProgress

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

Proprietà
  • totalBytes: dimensioni del pacchetto di aggiornamento di download, in byte. (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 "enumerazione" seguenti che possono essere usati per personalizzare l'esperienza di aggiornamento e sono disponibili a livello globale dall'oggetto window :

InstallMode

Questa enumerazione specificata quando si vuole applicare un aggiornamento installato e può essere passata ai sync metodi o LocalPackage.install . Include i valori seguenti:

  • IMMEDIATO: l'aggiornamento verrà applicato immediatamente all'applicazione in esecuzione. L'applicazione verrà ricaricata con il nuovo contenuto immediatamente.
  • ON_NEXT_RESTART: indica che si vuole installare l'aggiornamento, ma non riavviare in modo forcibly l'app. Quando l'app viene riavviata "naturalmente" (a causa del sistema operativo o dell'utente finale che lo uccide), l'aggiornamento verrà facilmente raccolto. Questo valore è appropriato quando si esegue aggiornamenti invisibile all'utente invisibile all'utente finale, poiché probabilmente l'utente finale è stato riavviato improvvisamente fuori da nessuna posizione, poiché non avrebbe capito 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 di 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, poiché gestirà automaticamente il processo di download e installazione.

Proprietà

L'oggetto RemotePackage eredita tutte le stesse proprietà dell'oggetto LocalPackage, ma 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. (Stringa)
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 più volte durante lo stato di avanzamento downloadProgress del download con un DownloadProgress parametro.
DownloadProgress

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

# Proprietà
  • totalBytes: dimensioni del pacchetto di aggiornamento di download, in byte. (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 "enumerazione" seguenti che possono essere usati per personalizzare l'esperienza di aggiornamento e sono disponibili a livello globale dall'oggetto window :

InstallMode

Questa enumerazione specificata quando si vuole applicare un aggiornamento installato e può essere passata ai sync metodi o LocalPackage.install . Include i valori seguenti:

  • IMMEDIATO: l'aggiornamento verrà applicato immediatamente all'applicazione in esecuzione. L'applicazione verrà ricaricata con il nuovo contenuto immediatamente.
  • ON_NEXT_RESTART: indica che si vuole installare l'aggiornamento, ma non riavviare in modo forcibly l'app. Quando l'app viene riavviata "naturalmente" (a causa del sistema operativo o dell'utente finale che lo uccide), l'aggiornamento verrà facilmente raccolto. Questo valore è appropriato quando si esegue aggiornamenti invisibile all'utente invisibile all'utente finale, poiché probabilmente l'utente finale è stato riavviato improvvisamente fuori da nessuna posizione, poiché non avrebbe capito 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 dell'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 riavvio naturale successivo. Questo valore è appropriato per le installazioni invisibile all'utente che possono essere applicate alla ripresa 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 lo stato 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: è stato installato un aggiornamento disponibile e verrà eseguito immediatamente dopo che la funzione di callback restituisce o la successiva volta che l'app riprende/riavvia, 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 viene updateDialog usato)
  • ERRORE: si è verificato un errore durante l'operazione sync . Potrebbe verificarsi un errore durante la comunicazione con il server, il download o l'annullamento del mapping 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: il server CodePush viene sottoposto a query 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 viene updateDialog usato)
  • DOWNLOADING_PACKAGE: viene scaricato un aggiornamento disponibile dal server CodePush.
  • INSTALLING_UPDATE: è stato scaricato un aggiornamento disponibile e sta per essere installato.

PhoneGap Build

Questo plug-in è compatibile con PhoneGap Build e supporta la creazione di Android e iOS build out-of-the-box. Tuttavia, per 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 diconfig.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 in modo gentile alcune app open source incredibili che possono servire come esempi per gli sviluppatori che si stanno avviando. L'elenco seguente è di app Cordova osS che usano anche CodePush e può essere usato per vedere come gli altri usano il servizio:

Nota

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