Kit de développement logiciel (SDK) client Cordova

Article
07/18/2024

Important

Visual Studio App Center est prévu pour la mise hors service le 31 mars 2025. Bien que vous puissiez continuer à utiliser Visual Studio App Center jusqu’à ce qu’il soit entièrement mis hors service, il existe plusieurs alternatives recommandées que vous pouvez envisager de migrer vers.

En savoir plus sur les chronologies de support et les alternatives.

Ce plug-in fournit une intégration côté client pour le service CodePush, ce qui vous permet d’ajouter facilement une expérience de mise à jour dynamique à vos applications Cordova.

Remarque

La prise en charge de Cordova Apps a pris fin en avril 2022. Pour plus d’informations, consultez le blog App Center.

Comment cela fonctionne-t-il ?

Une application Cordova est composée de fichiers HTML, CSS et JavaScript et d’images associées, qui sont regroupées ensemble par l’interface CLI Cordova et distribuées dans le cadre d’un binaire spécifique à la plateforme (c’est-à-dire un fichier .ipa ou .apk). Une fois l’application publiée, la mise à jour du code ou des ressources d’image vous oblige à recompiler et à redistribuer l’intégralité du fichier binaire. Ce processus inclut le temps d’examen du ou des magasins dans lequel vous publiez.

Le plug-in CodePush permet d’obtenir des améliorations de produit devant vos utilisateurs finaux instantanément, en gardant votre code et vos images synchronisées avec les mises à jour que vous publiez sur le serveur CodePush. De cette façon, votre application bénéficie des avantages d’une expérience mobile hors connexion, ainsi que de l’agilité « web-like » des mises à jour de chargement indépendant dès qu’elles sont disponibles. C’est un double avantage !

Pour vous assurer que vos utilisateurs finaux disposent toujours d’une version fonctionnelle de votre application, le plug-in CodePush conserve une copie de la mise à jour précédente, afin que, si vous envoyez accidentellement une mise à jour qui inclut un incident, elle peut automatiquement restaurer. De cette façon, vous pouvez vous assurer que votre agilité de mise en production nouvelle découverte n’entraîne pas le blocage des utilisateurs avant de pouvoir restaurer sur le serveur. C’est un win-win-win !

Remarque

Les modifications apportées au produit qui touchent le code natif (par exemple, la mise à niveau des versions cordova, l’ajout d’un nouveau plug-in) ne peuvent pas être distribuées via CodePush, et doivent donc être mises à jour via les magasins appropriés.

Plateformes Cordova prises en charge

Cordova 5.0.0+ est entièrement pris en charge, ainsi que les plateformes associées suivantes :

Android (cordova-android 4.0.0+) - Y compris CrossWalk !
iOS (cordova-ios 3.9.0+) - (Pour utiliser CodePush avec le cordova-plugin-wkwebview-engine plug-in, vous devez installer v1.5.1-beta+, ce qui inclut la prise en charge complète des applications à l’aide de WebView.)

Pour vérifier les versions de chaque plateforme Cordova que vous utilisez actuellement, vous pouvez exécuter la commande suivante et inspecter la Installed platforms liste :

    cordova platform ls

Si vous exécutez une plateforme Android ou iOS plus ancienne que celle mentionnée ci-dessus et que vous êtes ouvert à la mise à niveau, vous pouvez le faire facilement en exécutant les commandes suivantes (omettant une plateforme si ce n’est pas nécessaire) :

    cordova platform update android
    cordova platform update ios

Mise en route

Remarque

Cet article contient des références au terme liste verte, un terme que Microsoft n’utilise plus. Lorsque le terme sera supprimé du logiciel, nous le supprimerons de cet article.

Une fois que vous avez suivi les instructions de « prise en main » à usage général pour configurer votre compte CodePush, vous pouvez démarrer CodePush-ifier votre application Cordova en exécutant la commande suivante à partir du répertoire racine de votre application :

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

Une fois le plug-in CodePush installé, configurez votre application pour l’utiliser en procédant comme suit :

Ajoutez vos clés de déploiement au fichier config.xml , en veillant à inclure la clé appropriée pour chaque plateforme 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>

En guise de rappel, ces clés sont générées pour vous lorsque vous avez créé votre application CodePush via l’interface CLI. Si vous devez les récupérer, vous pouvez exécuter appcenter codepush deployment list -a <ownerName>/<appName> --displayKeyset saisir la clé pour le déploiement spécifique que vous souhaitez utiliser (par exempleStaging, ). Production

Important

Nous vous recommandons de créer une application CodePush distincte pour iOS et Android, ce qui explique pourquoi l’exemple ci-dessus déclare des clés distinctes pour Android et iOS. Si vous développez uniquement pour une plateforme unique, vous devez uniquement spécifier la clé de déploiement pour Android ou iOS. Vous n’avez donc pas besoin d’ajouter l’élément supplémentaire <platform> comme illustré ci-dessus.

À compter de la version 1.10.0, vous pouvez signer vos offres groupées de mises à jour (pour plus d’informations sur la signature de code, consultez la section relative à la documentation pertinente). Pour activer la signature de code pour une application Cordova, vous devez configurer une clé publique pour vérifier la signature du bundle en fournissant un preference paramètre dans config.xml:

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

Vous pouvez utiliser la même paire de clés privée/publique pour chaque plateforme.

Si vous utilisez un <access origin="*" /> élément dans votre fichier config.xml , votre application est déjà autorisée à communiquer avec les serveurs CodePush et vous pouvez ignorer cette étape en toute sécurité. Sinon, ajoutez les éléments supplémentaires <access /> suivants :

    <access origin="https://codepush.appcenter.ms" />
    <access origin="https://codepush.blob.core.windows.net" />
    <access origin="https://codepushupdates.azureedge.net" />

Pour vous assurer que votre application peut accéder au serveur CodePush sur des plateformes compatibles CSP, ajoutez https://codepush.appcenter.ms la Content-Security-Policy meta balise dans votre index.html fichier :

    <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 *" />

Enfin, vérifiez que le cordova-plugin-whitelist plug-in est déjà installé (la plupart des applications le feront). Pour vérifier cela, exécutez la commande suivante :

    cordova plugin ls

Si cordova-plugin-whitelist vous êtes dans la liste, alors vous êtes bon d’aller. Sinon, exécutez la commande suivante pour l’ajouter :

    cordova plugin add cordova-plugin-whitelist

Vous êtes maintenant prêt à utiliser le plug-in dans le code de l’application. Pour plus d’informations, consultez les exemples d’applications et la documentation de l’API.

Utilisation du plug-in

Avec le plug-in CodePush installé et configuré, la seule chose restante consiste à ajouter le code nécessaire à votre application pour contrôler les stratégies suivantes :

Quand (et à quelle fréquence) rechercher une mise à jour ? (e.g. app démarrer, en réponse à un clic sur un bouton dans une page de paramètres, régulièrement à un intervalle fixe)
Quand une mise à jour est disponible, comment la présenter à l’utilisateur final ? La méthode la plus simple consiste à exécuter ce qui suit dans le gestionnaire d’événements de deviceready votre application :

codePush.sync();

Si une mise à jour est disponible, elle est téléchargée en mode silencieux et installée la prochaine fois que l’application est redémarrée (explicitement par l’utilisateur final ou par le système d’exploitation), ce qui garantit l’expérience la moins invasive pour vos utilisateurs finaux. Si une mise à jour disponible est obligatoire, elle est installée immédiatement, ce qui garantit que l’utilisateur final l’obtient dès que possible.

Si vous souhaitez que votre application découvre les mises à jour plus rapidement, vous pouvez également choisir d’appeler sync chaque fois que l’application reprend à partir de l’arrière-plan, en ajoutant le code suivant (ou quelque chose d’équivalent) dans le cadre du comportement de démarrage de votre application. Vous pouvez appeler sync aussi fréquemment que vous le souhaitez, donc quand et où vous l’appelez dépend de vos préférences personnelles.

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

En outre, si vous souhaitez afficher une boîte de dialogue de confirmation de mise à jour (une « installation active »), configurez quand une mise à jour disponible est installée (par exemple, forcez un redémarrage immédiat) ou personnalisez l’expérience de mise à jour de quelque manière que ce soit, reportez-vous à la référence de l’API de la sync méthode pour plus d’informations sur la façon d’ajuster ce comportement par défaut.

Important

Bien que l’accord de développeur d’Apple autorise entièrement les mises à jour en direct de JavaScript et de ressources (c’est-à-dire ce qui active CodePush !), il est contre leur stratégie pour qu’une application affiche une invite de mise à jour. En raison de cela, nous vous recommandons que les applications distribuées par l’App Store n’activent pas l’option lors de l’appel updateDialog sync, tandis que Google Play et les applications distribuées en interne (par exemple, Enterprise, Fabric, HockeyApp) peuvent choisir d’activer/personnaliser celle-ci.

Publication des mises à jour

Une fois que votre application a été configurée et distribuée à vos utilisateurs, et que vous avez apporté des modifications de code ou de ressource, il est temps de les libérer instantanément ! La méthode la plus simple (et recommandée) consiste à utiliser la release-cordova commande dans l’interface CLI CodePush, qui gère la préparation et la publication de votre mise à jour sur le serveur CodePush.

Remarque

Avant de commencer à publier des mises à jour, connectez-vous à App Center en exécutant la appcenter login commande

Dans sa forme la plus simple, cette commande ne nécessite qu’un seul paramètre : votre nom de propriétaire + « / » + nom de l’application.

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

Conseil

En utilisant la fonction CLI set-current App Center, vous n’avez pas besoin d’utiliser l’indicateur -a pour spécifier l’application à laquelle une commande est dirigée.

Conseil

Lorsque vous publiez des mises à jour vers CodePush, vous n’avez pas besoin de faire passer la version de votre application dans le fichier config.xml , car vous ne modifiez pas la version binaire du tout. Vous devez uniquement mettre à niveau cette version lorsque vous mettez à niveau Cordova ou l’un de vos plug-ins, à ce stade, vous devez publier une mise à jour vers les magasins natifs. CodePush génère automatiquement une « étiquette » pour chaque version que vous effectuez (par exemple v3) pour vous aider à l’identifier dans votre historique de mise en production.

La release-cordova commande active un flux de travail si simple, car elle comprend la disposition standard d’une application Cordova, et ainsi de suite, peut générer votre mise à jour et savoir exactement quels fichiers charger. En outre, pour prendre en charge les stratégies de mise en production flexibles, la release-cordova commande expose de nombreux paramètres facultatifs qui vous permettent de personnaliser la façon dont la mise à jour doit être distribuée à vos utilisateurs finaux (par exemple, quelles versions binaires sont compatibles avec elle ? La version doit-elle être considérée comme obligatoire ?).

# 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

Le client CodePush prend en charge les mises à jour différentielles. Par conséquent, même si vous publiez le code de votre application sur chaque mise à jour, vos utilisateurs finaux téléchargent uniquement les fichiers dont ils ont besoin. Le service gère cela automatiquement afin que vous puissiez vous concentrer sur la création d’applications impressionnantes et nous pouvons nous soucier de l’optimisation des téléchargements des utilisateurs finaux.

Pour plus d’informations sur le fonctionnement de la release-cordova commande, ainsi que sur les différents paramètres qu’elle expose, reportez-vous à la documentation CLI. En outre, si vous préférez gérer l’exécution de la cordova prepare commande vous-même, et ainsi, souhaitez une solution encore plus flexible que release-cordova, reportez-vous à la release commande pour plus de détails.

Si vous rencontrez des problèmes ou que vous avez des questions/commentaires/commentaires, vous pouvez nous envoyer un e-mail ou ouvrir un nouveau problème sur ce dépôt et nous répondrons à ASAP ! Consultez également l’aide et les commentaires.

Référence d’API

L’API CodePush est exposée à votre application via l’objet global codePush , disponible après le déclenchement de l’événement deviceready . Cette API expose les méthodes de niveau supérieur suivantes :

checkForUpdate : demande au service CodePush si le déploiement d’application configuré a une mise à jour disponible.
getCurrentPackage : récupère les métadonnées relatives à la mise à jour actuellement installée (par exemple, description, heure d’installation, taille).
getPendingPackage : récupère les métadonnées d’une mise à jour (s’il en existe) qui a été téléchargée et installée, mais n’a pas encore été appliquée via un redémarrage.
notifyApplicationReady : notifie le runtime CodePush qu’une mise à jour installée est considérée comme réussie. Si vous recherchez et installez manuellement les mises à jour (c’est-à-dire que vous n’utilisez pas la méthode de synchronisation pour gérer tout pour vous), cette méthode DOIT être appelée ; sinon, CodePush traite la mise à jour comme ayant échoué et revient à la version précédente lors du prochain redémarrage de l’application.
restartApplication : redémarre immédiatement l’application. S’il existe une mise à jour en attente, elle s’affiche immédiatement à l’utilisateur final.
synchronisation : permet de rechercher une mise à jour, de la télécharger et de l’installer, avec un seul appel. Sauf si vous avez besoin d’une interface utilisateur ou d’un comportement personnalisé, nous recommandons à la plupart des développeurs d’utiliser cette méthode lors de l’intégration de CodePush dans leurs applications.

En outre, les objets et énumérations suivants sont également exposés globalement dans le cadre de l’API CodePush :

InstallMode : définit les modes d’installation disponibles pour les mises à jour.
LocalPackage : contient des informations sur un package installé localement.
RemotePackage : contient des informations sur un package de mise à jour disponible en téléchargement.
SyncStatus : définit les états intermédiaires et de résultats possibles de l’opération de synchronisation .

codePush.checkForUpdate

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

Interroge le service CodePush pour déterminer si le déploiement d’application configuré dispose d’une mise à jour disponible. Par défaut, elle utilise la clé de déploiement configurée dans votre fichier config.xml , mais vous pouvez la remplacer en spécifiant une valeur via le paramètre facultatif deploymentKey . Cela peut être utile lorsque vous souhaitez « rediriger » dynamiquement un utilisateur vers un déploiement spécifique, par exemple autoriser « Accès anticipé » via un œuf de pâques ou un commutateur de paramètre utilisateur.

Une fois la vérification de mise à jour terminée, elle déclenche le onUpdateCheck rappel avec l’une des deux valeurs possibles :

null s’il n’existe aucune mise à jour disponible. Cela se produit dans les scénarios suivants :
- Le déploiement configuré ne contient aucune version. Il n’y a donc rien à mettre à jour.
- La dernière version du déploiement configuré cible une version binaire différente de celle que vous exécutez actuellement (plus ancienne ou ultérieure).
- L’application en cours d’exécution dispose déjà de la dernière version du déploiement configuré. Elle n’a donc pas besoin de la version à nouveau.
Instance RemotePackage qui représente une mise à jour disponible qui peut être inspectée et téléchargée ultérieurement.

Paramètres :

onSuccess : rappel appelé lors de la réception d’une réponse réussie du serveur. Le rappel reçoit un paramètre unique, décrit ci-dessus.
onError : rappel facultatif appelé en cas d’erreur. Le rappel prend un paramètre d’erreur, contenant les détails de l’erreur.
deploymentKey : clé de déploiement facultative qui remplace le paramètre de config.xml .

Exemple d'utilisation :

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?);

Récupère les métadonnées relatives au « package » actuellement installé (par exemple, description, heure d’installation). Cela peut être utile pour les scénarios tels que l’affichage d’une boîte de dialogue « Nouveautés ? » une fois qu’une mise à jour a été appliquée ou vérifie s’il existe une mise à jour en attente qui attend d’être appliquée via un cv ou un redémarrage.

Une fois la récupération de mise à jour terminée, elle déclenche le onSuccess rappel avec l’une des deux valeurs possibles :

null si l’application exécute actuellement la page de démarrage HTML à partir du fichier binaire et non d’une mise à jour CodePush. Cela se produit dans les scénarios suivants :
- L’utilisateur final a installé le fichier binaire de l’application et n’a pas encore installé une mise à jour CodePush
- L’utilisateur final a installé une mise à jour du fichier binaire (par exemple, à partir du magasin), qui a effacé les anciennes mises à jour CodePush et a donné priorité au fichier binaire.
Instance LocalPackage qui représente les métadonnées de la mise à jour CodePush en cours d’exécution.

Paramètres :

onSuccess : rappel appelé lors de la réception des métadonnées relatives à la mise à jour en cours d’exécution. Le rappel reçoit un paramètre unique, décrit ci-dessus.
onError : rappel facultatif appelé en cas d’erreur. Le rappel prend un paramètre d’erreur, contenant les détails de l’erreur.

Exemple d’utilisation :

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?);

Obtient les métadonnées de la mise à jour en attente (le cas échéant). Une mise à jour est considérée comme « en attente » si elle a été téléchargée et installée, mais n’a pas encore été appliquée via un redémarrage d’application. Une mise à jour ne peut jamais être dans cet état si InstallMode.ON_NEXT_RESTART ou InstallMode.ON_NEXT_RESUME ont été spécifiées lors de l’appel sync ou LocalPackage.install, et l’application n’a pas encore été redémarrée ou reprise (respectivement). Cette méthode peut être utile si vous souhaitez déterminer s’il existe une mise à jour en attente, puis inviter l’utilisateur à redémarrer immédiatement (via codePush.restartApplication) pour l’appliquer.

Une fois la récupération de mise à jour terminée, elle déclenche le onSuccess rappel avec l’une des deux valeurs possibles :

null si l’application n’a actuellement pas de mise à jour en attente (par exemple, l’application exécute déjà la dernière version disponible).
Instance LocalPackage qui représente les métadonnées de la mise à jour CodePush en attente.

Paramètres :

onSuccess : rappel appelé lors de la réception des métadonnées relatives à la mise à jour en attente. Le rappel reçoit un paramètre unique, décrit ci-dessus.
onError : rappel facultatif appelé en cas d’erreur. Le rappel prend un paramètre d’erreur, contenant les détails de l’erreur.

Exemple d’utilisation :

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?);

Avertit le runtime CodePush qu’une mise à jour fraîchement installée doit être considérée comme réussie. Par conséquent, une restauration automatique côté client n’est pas nécessaire. Il est obligatoire d’appeler cette fonction quelque part dans le code du bundle mis à jour. Dans le cas contraire, lorsque l’application redémarre ensuite, le runtime CodePush suppose que la mise à jour installée a échoué et revient à la version précédente. Ce comportement existe pour vous assurer que vos utilisateurs finaux ne sont pas bloqués par une mise à jour interrompue.

Si vous utilisez la sync fonction et que vous effectuez votre vérification de mise à jour au démarrage de l’application, vous n’avez pas besoin d’appeler notifyApplicationReady manuellement, car sync vous l’appelez pour vous. Ce comportement existe en raison de l’hypothèse que lorsqu’elle sync est appelée dans votre application représente une bonne approximation d’un démarrage réussi.

Paramètres :

notifySucceeded : rappel facultatif appelé si le plug-in a été correctement notifié.
notifyFailed : rappel facultatif appelé en cas d’erreur signalant le plug-in.

codePush.restartApplication

codePush.restartApplication();

Redémarre immédiatement l’application. Cette méthode est destinée aux scénarios avancés et est principalement utile lorsque les conditions suivantes sont remplies :

Votre application spécifie une valeur de mode d’installation de ou ON_NEXT_RESUME lors de ON_NEXT_RESTART l’appel des méthodes ou LocalPackage.install des sync méthodes. Cela n’applique pas votre mise à jour tant que l’application ne redémarre pas (par l’utilisateur final ou le système d’exploitation) ou reprend, de sorte que la mise à jour ne s’affiche pas immédiatement à l’utilisateur final.
Vous disposez d’un événement utilisateur spécifique à l’application (par exemple, l’utilisateur final a accédé à l’itinéraire d’accueil de l’application) qui vous permet d’appliquer la mise à jour de manière discrète et d’obtenir potentiellement la mise à jour devant l’utilisateur final plus tôt que d’attendre le redémarrage ou la reprise suivant.

codePush.sync

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

Synchronise le code et les images de votre application avec la dernière version du déploiement configuré. Contrairement à la checkForUpdate méthode, qui vérifie la présence d’une mise à jour et vous permet de contrôler les étapes à suivre, gère la vérification des mises à jour, sync le téléchargement et l’expérience d’installation pour vous.

Cette méthode prend en charge deux « modes » différents (mais personnalisables) pour activer facilement les applications avec des exigences différentes :

Mode silencieux (comportement par défaut) qui télécharge automatiquement les mises à jour disponibles et les applique la prochaine fois que l’application redémarre (par exemple, le système d’exploitation ou l’utilisateur final l’a tué, ou l’appareil a été redémarré). De cette façon, toute l’expérience de mise à jour est « silencieuse » pour l’utilisateur final, car elle ne voit aucune invite de mise à jour ni redémarrage de l’application « synthétique ».
Mode actif, qui, lorsqu’une mise à jour est disponible, invite l’utilisateur final à obtenir l’autorisation avant de le télécharger, puis applique immédiatement la mise à jour. Si une mise à jour a été publiée à l’aide de l’indicateur obligatoire, l’utilisateur final serait toujours informé de la mise à jour, mais il n’aurait pas le choix de l’ignorer.

Exemple d’utilisation :

// 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 });

Conseil

Si vous souhaitez déterminer si vous vérifiez ou téléchargez une mise à jour disponible en fonction du niveau de batterie de l’appareil de l’utilisateur final, des conditions réseau, etc. encapsulez l’appel pour la synchroniser dans une condition qui garantit que vous l’appelez uniquement lorsque vous le souhaitez.

Bien que la méthode de synchronisation tente d’effectuer facilement des mises à jour silencieuses et actives avec peu de configuration, elle accepte les paramètres facultatifs suivants qui vous permettent de personnaliser de nombreux aspects du comportement par défaut mentionné ci-dessus :

syncCallback : appelé lorsque le processus de synchronisation passe d’une étape à l’autre dans le processus de mise à jour globale. La méthode est appelée avec un code d’état qui représente l’état actuel et peut être l’une des SyncStatus valeurs.
syncOptions : paramètre facultatif SyncOptions configurant le comportement de l’opération de synchronisation.
downloadProgress : appelé régulièrement lorsqu’une mise à jour disponible est téléchargée à partir du serveur CodePush. La méthode est appelée avec un DownloadProgress objet, qui contient les deux propriétés suivantes :
- totalBytes (Number) : nombre total d’octets attendu pour cette mise à jour (c’est-à-dire la taille de l’ensemble de fichiers modifié par rapport à la version précédente).
- receivedBytes (Number) : nombre d’octets téléchargés jusqu’à présent, qui peuvent être utilisés pour suivre la progression du téléchargement.
syncErrback : appelé en cas d’erreur dans l’une des étapes internes de synchronisation. La méthode est appelée avec un objet javascript Error standard comme premier argument.

SyncOptions

Bien que la sync méthode tente de faciliter les mises à jour silencieuses et actives avec peu de configuration, elle accepte un objet « options » qui vous permet de personnaliser de nombreux aspects du comportement par défaut mentionné ci-dessus :

deploymentKey (string) : spécifie la clé de déploiement à laquelle vous souhaitez interroger une mise à jour. Par défaut, cette valeur est dérivée du fichier config.xml , mais cette option vous permet de la remplacer du côté script si vous devez utiliser dynamiquement un autre déploiement pour un appel spécifique à sync.
installMode (InstallMode) : spécifie quand vous souhaitez installer des mises à jour facultatives (c’est-à-dire celles qui ne sont pas marquées comme obligatoires). La valeur par défaut est InstallMode.ON_NEXT_RESTART. Reportez-vous à la InstallMode référence d’énumération pour obtenir une description des options disponibles et de ce qu’elles font.
mandatoryInstallMode (InstallMode) : spécifie quand vous souhaitez installer des mises à jour marquées comme obligatoires. La valeur par défaut est InstallMode.IMMEDIATE. Reportez-vous à la InstallMode référence d’énumération pour obtenir une description des options disponibles et de ce qu’elles font.
minimumBackgroundDuration (Nombre) : spécifie le nombre minimal de secondes pour que l’application soit en arrière-plan avant de redémarrer l’application. Cette propriété s’applique uniquement aux mises à jour qui sont installées à l’aide InstallMode.ON_NEXT_RESUME, et peut être utile pour obtenir votre mise à jour avant les utilisateurs finaux plus tôt, sans être trop obtrusive. 0La valeur par défaut est , qui applique la mise à jour immédiatement après une reprise, mais longue qu’elle était en arrière-plan.
ignoreFailedUpdates (booléen) : spécifie si une mise à jour disponible doit être ignorée si elle avait été précédemment installée et restaurée sur le client (car notifyApplicationReady elle n’a pas été appelée avec succès). La valeur par défaut est true.
updateDialog (UpdateDialogOptions) : objet « options » utilisé pour déterminer si une boîte de dialogue de confirmation doit être affichée à l’utilisateur final lorsqu’une mise à jour est disponible et, le cas échéant, quelles chaînes utiliser. La valeur par défaut est null, ce qui désactive la boîte de dialogue. La définition de cette true valeur active la boîte de dialogue avec les chaînes par défaut et le passage d’un objet à ce paramètre permet d’activer la boîte de dialogue, ainsi que de remplacer une ou plusieurs des chaînes par défaut.

La liste suivante représente les options disponibles et leurs valeurs par défaut :

appendReleaseDescription (booléen) : indique si vous souhaitez ajouter la description d’une version disponible au message de notification affiché à l’utilisateur final. La valeur par défaut est false.
descriptionPrefix (chaîne) : indique la chaîne avec laquelle vous souhaitez préfixer la description de mise en production, le cas échéant, lors de l’affichage de la notification de mise à jour à l’utilisateur final. La valeur par défaut est " Description: ".
mandatoryContinueButtonLabel (String) : texte à utiliser pour le bouton sur lequel l’utilisateur final doit appuyer pour installer une mise à jour obligatoire. La valeur par défaut est "Continue".
mandatoryUpdateMessage (String) : texte utilisé comme corps d’une notification de mise à jour, lorsque la mise à jour est spécifiée comme obligatoire. La valeur par défaut est "An update is available that must be installed.".
optionalIgnoreButtonLabel (String) : texte à utiliser pour le bouton sur lequel l’utilisateur final peut appuyer pour ignorer une mise à jour facultative disponible. La valeur par défaut est "Ignore".
optionalInstallButtonLabel (String) : texte à utiliser pour le bouton sur lequel l’utilisateur final peut appuyer pour installer une mise à jour facultative. La valeur par défaut est "Install".
optionalUpdateMessage (String) : texte utilisé comme corps d’une notification de mise à jour, lorsque la mise à jour est facultative. La valeur par défaut est "An update is available. Would you like to install it?". *- updateTitle (String) : texte utilisé comme en-tête d’une notification de mise à jour affichée à l’utilisateur final. La valeur par défaut est "Update available".

Exemple d’utilisation :

// 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);
    }
}

La sync méthode peut être appelée partout où vous souhaitez rechercher une mise à jour. Cela peut se trouver dans le deviceready gestionnaire d’événements, l’événement click d’un bouton, dans le rappel d’un minuteur périodique, ou tout autre élément logique pour vos besoins. Comme la checkForUpdate méthode, elle exécute la requête réseau pour rechercher une mise à jour en arrière-plan. Elle n’aura donc pas d’impact sur la réactivité de votre thread d’interface utilisateur ou du thread JavaScript.

Objets de package

Les checkForUpdate méthodes et getCurrentPackage appellent les rappels de réussite, qui, lorsqu’ils sont déclenchés, fournissent l’accès aux objets « package ». Le package représente votre mise à jour de code ainsi que toutes les métadonnées supplémentaires (par exemple, description, obligatoire ?). L’API CodePush a la distinction entre les types de packages suivants :

LocalPackage: représente une mise à jour téléchargée qui est déjà en cours d’exécution ou qui a été installée et qui est en attente de redémarrage de l’application.
RemotePackage: représente une mise à jour disponible sur le serveur CodePush qui n’a pas encore été téléchargé.

LocalPackage

Contient des détails sur une mise à jour qui a été téléchargée localement ou déjà installée. Vous pouvez obtenir une référence à une instance de cet objet en appelant la codePush.getCurrentPackage méthode ou en tant que valeur fournie au rappel de réussite de la RemotePackage.download méthode.

Propriétés

appVersion : la version native de l’application pour laquelle cette mise à jour de package est destinée. (String)
deploymentKey : clé de déploiement du package. (String)
description : description de la mise à jour. Il s’agit de la même valeur que celle que vous avez spécifiée dans l’interface CLI lorsque vous avez publié la mise à jour. (String)
ÉchecInstall : indique si cette mise à jour a été précédemment installée, mais a été restaurée. La sync méthode ignore automatiquement les mises à jour qui ont échoué précédemment. Vous devez donc vous soucier uniquement de cette propriété si vous utilisez checkForUpdate. (Boolean)
isFirstRun : indicateur indiquant si l’exécution de l’application actuelle est la première après l’application du package. (Boolean)
isMandatory : indique si la mise à jour est considérée comme obligatoire. Il s’agit de la valeur spécifiée dans l’interface CLI lors de la publication de la mise à jour. (Boolean)
étiquette : étiquette interne automatiquement donnée à la mise à jour par le serveur CodePush, par v5exemple . Cette valeur identifie de manière unique la mise à jour au sein de son déploiement. (String)
packageHash : valeur de hachage SHA de la mise à jour. (String)
packageSize : taille du code contenu dans la mise à jour, en octets. (Nombre)

Méthodes

install(installSuccess, installError, installOptions) : installe ce package dans l’application. Le comportement d’installation dépend du paramètre fourni installOptions. Par défaut, le package de mise à jour est installé en mode silencieux et l’application est rechargée avec le nouveau contenu au démarrage de l’application suivante. Lors de la première exécution après la mise à jour, l’application attend un codePush.notifyApplicationReady() appel. Une fois cet appel effectué, l’opération d’installation est considérée comme une réussite. Sinon, l’opération d’installation est marquée comme ayant échoué et l’application est rétablie à sa version précédente lors de la prochaine exécution.

InstallOptions

Interface définissant plusieurs options pour personnaliser le comportement de l’opération d’installation.

installMode : utilisé pour spécifier le InstallMode utilisé pour l’opération d’installation. La valeur par défaut est InstallMode.ON_NEXT_RESTART.
mandatoryInstallMode : utilisé pour spécifier le InstallMode utilisé pour l’opération d’installation si le package est obligatoire. La valeur par défaut est InstallMode.IMMEDIATE.
minimumBackgroundDuration : si installMode est InstallMode.ON_NEXT_RESUMEutilisé pour spécifier la durée pendant laquelle l’application doit être en arrière-plan avant l’installation de la mise à jour lors de sa reprise. La valeur par défaut est 0.

Exemple d’utilisation :

// 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();
        // ...
    }
}

Pour obtenir un exemple sur la façon dont vous êtes protégé contre une mise à jour incorrecte, consultez la documentation notifyApplicationReady().

RemotePackage

Contient des détails sur une mise à jour disponible pour le téléchargement à partir du serveur CodePush. Vous obtenez une référence à une instance de cet objet en appelant la codePush.checkForUpdate méthode lorsqu’une mise à jour est disponible. Si vous utilisez l’API de synchronisation, vous n’avez pas besoin de vous soucier RemotePackagedu processus de téléchargement et d’installation automatiquement.

Propriétés

Il RemotePackage hérite de toutes les mêmes propriétés que le LocalPackage, mais inclut un autre :

downloadUrl : URL où le package est disponible pour le téléchargement. Cette propriété n’est nécessaire qu’à une utilisation avancée, car la download méthode gère automatiquement l’acquisition des mises à jour pour vous. (String)

Méthodes

abortDownload(abortSuccess, abortError) : abandonne la session de téléchargement actuelle, le cas échéant.
download(downloadSuccess, downloadError, downloadProgress) : télécharge la mise à jour du package à partir du service CodePush. Le downloadSuccess rappel est appelé avec un argument LocalPackage représentant le package téléchargé. Le rappel facultatif downloadProgress est appelé plusieurs fois pendant la progression du téléchargement avec un DownloadProgress paramètre.

DownloadProgress

Définit le format de l’objet DownloadProgress, utilisé pour envoyer des notifications de mise à jour périodiques sur la progression du téléchargement de la mise à jour.

Propriétés

totalBytes : taille du package de mise à jour téléchargé, en octets. (Nombre)
receivedBytes : nombre d’octets déjà téléchargés. (Nombre)

Exemple d’utilisation :

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);

Énumérations

L’API CodePush inclut les objets « enum » suivants qui peuvent être utilisés pour personnaliser l’expérience de mise à jour et sont disponibles globalement hors de l’objet window :

InstallMode

Cette énumération spécifiée lorsque vous souhaitez qu’une mise à jour installée soit appliquée, et peut être passée à l’une ou LocalPackage.install l’autre des sync méthodes. Il inclut les valeurs suivantes :

EXÉCUTION : la mise à jour est appliquée immédiatement à l’application en cours d’exécution. L’application sera rechargée immédiatement avec le nouveau contenu.
ON_NEXT_RESTART : indique que vous souhaitez installer la mise à jour, mais pas redémarrer de force l’application. Lorsque l’application est « naturellement » redémarrée (en raison du système d’exploitation ou de l’utilisateur final qui l’a tué), la mise à jour sera récupérée en toute transparence. Cette valeur est appropriée lorsque vous effectuez des mises à jour silencieuses, car elle serait probablement perturbante pour l’utilisateur final si l’application a soudainement redémarré hors de nulle part, car elle n’aurait pas réalisé qu’une mise à jour était même téléchargée. Il s’agit du mode par défaut utilisé pour les méthodes et LocalPackage.install les sync méthodes.

Pour obtenir un exemple sur la façon dont vous êtes protégé contre une mise à jour incorrecte, consultez la documentation notifyApplicationReady().

RemotePackage

Propriétés

Il RemotePackage hérite de toutes les mêmes propriétés que le LocalPackage, mais inclut un autre :

downloadUrl : URL où le package est disponible pour le téléchargement. Cette propriété n’est nécessaire qu’à une utilisation avancée, car la download méthode gère automatiquement l’acquisition des mises à jour pour vous. (String)

Méthodes

abortDownload(abortSuccess, abortError) : abandonne la session de téléchargement actuelle, le cas échéant.
download(downloadSuccess, downloadError, downloadProgress) : télécharge la mise à jour du package à partir du service CodePush. Le downloadSuccess rappel est appelé avec un argument LocalPackage représentant le package téléchargé. Le rappel facultatif downloadProgress est appelé plusieurs fois pendant la progression du téléchargement avec un DownloadProgress paramètre.

DownloadProgress

Définit le format de l’objet DownloadProgress, utilisé pour envoyer des notifications de mise à jour périodiques sur la progression du téléchargement de la mise à jour.

# Propriétés

totalBytes : taille du package de mise à jour téléchargé, en octets. (Nombre)
receivedBytes : nombre d’octets déjà téléchargés. (Nombre)

Exemple d’utilisation :

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);

Énumérations

L’API CodePush inclut les objets « enum » suivants qui peuvent être utilisés pour personnaliser l’expérience de mise à jour et sont disponibles globalement hors de l’objet window :

InstallMode

EXÉCUTION : la mise à jour est appliquée immédiatement à l’application en cours d’exécution. L’application sera rechargée immédiatement avec le nouveau contenu.
ON_NEXT_RESTART : indique que vous souhaitez installer la mise à jour, mais pas redémarrer de force l’application. Lorsque l’application est « naturellement » redémarrée (en raison du système d’exploitation ou de l’utilisateur final qui l’a tué), la mise à jour sera récupérée en toute transparence. Cette valeur est appropriée lorsque vous effectuez des mises à jour silencieuses, car elle serait probablement perturbante pour l’utilisateur final si l’application a soudainement redémarré hors de nulle part, car elle n’aurait pas réalisé qu’une mise à jour était même téléchargée. Il s’agit du mode par défaut utilisé pour les méthodes et LocalPackage.install les sync méthodes.
ON_NEXT_RESUME : indique que vous souhaitez installer la mise à jour, mais que vous ne souhaitez pas redémarrer l’application tant que l’utilisateur final ne le reprend pas à partir de l’arrière-plan. De cette façon, vous n’interrompez pas leur session actuelle, mais vous pouvez obtenir la mise à jour devant eux plus tôt que de devoir attendre le prochain redémarrage naturel. Cette valeur est appropriée pour les installations silencieuses qui peuvent être appliquées à la reprise de manière non invasive.

SyncStatus

Définit les états possibles de l’opération de synchronisation . Il existe deux catégories d’états : intermédiaire et résultat (final). Les états intermédiaires représentent les états de progression de l’opération de synchronisation et ne sont pas définitifs. Les états de résultat représentent les états finaux de l’opération de synchronisation. Chaque opération de synchronisation se termine par un seul état de résultat, mais peut avoir zéro ou plusieurs états intermédiaires.

UP_TO_DATE : l’application est entièrement à jour avec le déploiement configuré.
UPDATE_INSTALLED : une mise à jour disponible a été installée et sera exécutée immédiatement après le retour de la fonction de rappel ou la prochaine fois que l’application reprend/redémarre, en fonction de l’élément InstallMode spécifié.SyncOptions
UPDATE_IGNORED : l’application a une mise à jour facultative, que l’utilisateur final a choisi d’ignorer. (Cela s’applique uniquement lorsque celui-ci updateDialog est utilisé)
ERREUR : une erreur s’est produite pendant l’opération sync . Il peut s’agir d’une erreur lors de la communication avec le serveur, du téléchargement ou de la désactivation de la mise à jour. Les journaux de la console doivent contenir plus d’informations sur ce qui s’est passé. Aucune mise à jour n’a été appliquée dans ce cas.
IN_PROGRESS : une autre synchronisation est déjà en cours d’exécution. Cette tentative de synchronisation a donc été abandonnée.
CHECKING_FOR_UPDATE : Le serveur CodePush est interrogé pour une mise à jour.
AWAITING_USER_ACTION : une mise à jour est disponible et une boîte de dialogue de confirmation a été affichée à l’utilisateur final. (Cela s’applique uniquement lorsque celui-ci updateDialog est utilisé)
DOWNLOADING_PACKAGE : une mise à jour disponible est téléchargée à partir du serveur CodePush.
INSTALLING_UPDATE : une mise à jour disponible a été téléchargée et est sur le point d’être installée.

PhoneGap Build

Ce plug-in est compatible avec PhoneGap Build et prend en charge la création de builds Android et iOS prêtes à l’emploi. Toutefois, pour que CodePush calcule le hachage de votre contenu binaire sur Android, PhoneGap Build doit utiliser Gradle pour générer votre application, ce qui n’est pas son comportement par défaut (il utilise Ant). Pour résoudre ce problème, ajoutez l’élément suivant au fichier config.xml du projet, en tant qu’enfant de l’élément <platform name="android"> :

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

Exemples d’applications

La communauté Cordova a créé des applications code source ouvert impressionnantes qui peuvent servir d’exemples pour les développeurs qui commencent. La liste suivante est des applications OSS Cordova qui utilisent également CodePush et qui peuvent être utilisées pour voir comment les autres utilisent le service :

PGDay CodePush Demo - Application de démonstration créée par Rangle.io utilisée pour PhoneGap Day Europe 2016.

Remarque

Si vous avez développé une application Cordova à l’aide de CodePush, c’est open source, faites-nous savoir. Nous aimerions l’ajouter à cette liste !

Partager via

Kit de développement logiciel (SDK) client Cordova

Comment cela fonctionne-t-il ?

Plateformes Cordova prises en charge

Mise en route

Utilisation du plug-in

Publication des mises à jour

Référence d’API

codePush.checkForUpdate

codePush.getCurrentPackage

codePush.getPendingPackage

codePush.notifyApplicationReady

codePush.restartApplication

codePush.sync

SyncOptions

Objets de package

LocalPackage

Propriétés

Méthodes

InstallOptions

RemotePackage

Propriétés

Méthodes

DownloadProgress

Propriétés

Énumérations

InstallMode

RemotePackage

Propriétés

Méthodes

DownloadProgress

# Propriétés

Énumérations

InstallMode

SyncStatus

PhoneGap Build

Exemples d’applications

Commentaires

Ressources supplémentaires