Compartir a través de

SDK de cliente de Cordova

  • Artículo

Importante

Visual Studio App Center está programado para su retirada el 31 de marzo de 2025. Aunque puede seguir usando Visual Studio App Center hasta que se retire por completo, hay varias alternativas recomendadas a las que puede considerar la posibilidad de migrar.

Obtenga más información sobre las escalas de tiempo de soporte técnico y las alternativas.

Este complemento proporciona integración del lado cliente para el servicio CodePush, lo que le permite agregar fácilmente una experiencia de actualización dinámica a las aplicaciones cordova.

Nota:

La compatibilidad con cordova Apps finalizó en abril de 2022. Obtenga más información en el blog de App Center.

¿Cómo funciona?

Una aplicación cordova se compone de archivos HTML, CSS y JavaScript y cualquier imagen adjunta, agrupada por la CLI de Cordova y distribuida como parte de un archivo binario específico de la plataforma (es decir, un archivo .ipa o .apk). Una vez publicada la aplicación, la actualización de los recursos de código o imagen requiere que vuelvas a compilar y redistribuir todo el binario. Este proceso incluye el tiempo de revisión de las tiendas en las que está publicando.

El complemento CodePush ayuda a obtener mejoras en el producto delante de los usuarios finales al instante, manteniendo el código y las imágenes sincronizados con las actualizaciones que publique en el servidor CodePush. De este modo, la aplicación obtiene las ventajas de una experiencia móvil sin conexión, así como la agilidad "similar a la web" de las actualizaciones de carga local tan pronto como estén disponibles. ¡Son todo ventajas!

Para asegurarse de que los usuarios finales siempre tienen una versión en funcionamiento de la aplicación, el complemento CodePush mantiene una copia de la actualización anterior, de modo que, en caso de que inserte accidentalmente una actualización que incluya un bloqueo, puede revertirse automáticamente. De este modo, puede estar seguro de que la agilidad de lanzamiento de la nueva versión no dará lugar a que los usuarios se bloqueen antes de tener la oportunidad de revertir en el servidor. ¡Es un win-win-win!

Nota:

Cualquier cambio de producto que toque código nativo (por ejemplo, actualizar versiones de Cordova, agregar un nuevo complemento) no se puede distribuir a través de CodePush, por lo que debe actualizarse a través de los almacenes adecuados.

Plataformas cordova admitidas

Cordova 5.0.0+ es totalmente compatible, junto con las siguientes plataformas asociadas:

Para comprobar las versiones de cada plataforma de Cordova que está usando actualmente, puede ejecutar el siguiente comando e inspeccionar la Installed platforms lista:

    cordova platform ls

Si ejecuta una plataforma de Android o iOS anterior a la mencionada anteriormente y estaría abierta a la actualización, puede hacerlo fácilmente ejecutando los siguientes comandos (omitiendo una plataforma si no es necesario):

    cordova platform update android
    cordova platform update ios

Introducción

Nota:

Este artículo contiene referencias al término lista blanca, un término que Microsoft ya no usa. Cuando se quite el término del software, se quitará también del artículo.

Una vez que haya seguido las instrucciones de "introducción" de uso general para configurar la cuenta de CodePush, puede iniciar CodePush-ify la aplicación Cordova ejecutando el siguiente comando desde el directorio raíz de la aplicación:

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

Con el complemento CodePush instalado, configure la aplicación para usarla mediante los pasos siguientes:

  1. Agregue las claves de implementación al archivo config.xml , asegurándose de incluir la clave adecuada para cada plataforma de 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>

Como recordatorio, estas claves se generan automáticamente al crear la aplicación CodePush a través de la CLI. Si necesita recuperarlos, puede ejecutar appcenter codepush deployment list -a <ownerName>/<appName> --displayKeysy tomar la clave para la implementación específica que desea usar (por ejemplo Staging, , Production).

Importante

Se recomienda crear una aplicación CodePush independiente para iOS y Android, por lo que el ejemplo anterior declara claves independientes para Android e iOS. Si solo está desarrollando para una sola plataforma, solo tiene que especificar la clave de implementación para Android o iOS, por lo que no es necesario agregar el elemento adicional <platform> como se muestra anteriormente.

A partir de la versión 1.10.0, puede firmar los paquetes de actualizaciones (para obtener más información sobre la firma de código, consulte la sección de documentación pertinente). Para habilitar la firma de código para una aplicación cordova, debe configurar una clave pública para comprobar la firma del lote proporcionando una preference configuración de :config.xml

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

Puede usar el mismo par de claves privadas o públicas para cada plataforma.

  1. Si usa un <access origin="*" /> elemento en el archivo de config.xml , la aplicación ya puede comunicarse con los servidores CodePush y puede omitir este paso de forma segura. De lo contrario, agregue los siguientes elementos adicionales <access /> :
    <access origin="https://codepush.appcenter.ms" />
    <access origin="https://codepush.blob.core.windows.net" />
    <access origin="https://codepushupdates.azureedge.net" />
  1. Para asegurarse de que la aplicación puede acceder al servidor CodePush en plataformas compatibles con CSP, agregue https://codepush.appcenter.ms a la etiqueta en index.html el Content-Security-Policy meta archivo:
    <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. Por último, compruebe que ya tiene instalado el cordova-plugin-whitelist complemento (la mayoría de las aplicaciones). Para comprobarlo, ejecute el siguiente comando:
    cordova plugin ls

Si cordova-plugin-whitelist está en la lista, entonces es bueno ir. De lo contrario, ejecute el siguiente comando para agregarlo:

    cordova plugin add cordova-plugin-whitelist

Ya está listo para usar el complemento en el código de la aplicación. Consulte las aplicaciones de ejemplo para obtener ejemplos y la documentación de api para obtener más detalles.

Uso del complemento

Con el complemento CodePush instalado y configurado, lo único que queda es agregar el código necesario a la aplicación para controlar las siguientes directivas:

  1. ¿Cuándo (y con qué frecuencia) buscar una actualización? (e.g. app inicio, en respuesta a hacer clic en un botón en una página de configuración, periódicamente a intervalo fijo)
  2. Cuando haya una actualización disponible, ¿cómo presentarla al usuario final? La manera más sencilla de hacerlo es ejecutar lo siguiente en el controlador de eventos de la deviceready aplicación:
codePush.sync();

Si hay disponible una actualización, se descargará de forma silenciosa e instalará la próxima vez que se reinicie la aplicación (ya sea explícitamente por el usuario final o por el sistema operativo), lo que garantiza la experiencia menos invasiva para los usuarios finales. Si una actualización disponible es obligatoria, se instalará inmediatamente, asegurándose de que el usuario final lo obtenga lo antes posible.

Si quieres que la aplicación detecte actualizaciones más rápidamente, también puedes optar por llamar sync cada vez que la aplicación se reanuda desde segundo plano agregando el código siguiente (o algo equivalente) como parte del comportamiento de inicio de la aplicación. Puedes llamar sync con la frecuencia que quieras, así que cuándo y dónde lo llamas depende de tu preferencia personal.

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

Además, si desea mostrar un cuadro de diálogo de confirmación de actualización (una "instalación activa"), configure cuando se instale una actualización disponible (por ejemplo, forzar un reinicio inmediato) o personalizar la experiencia de actualización de cualquier manera, consulte la sync referencia de API del método para obtener información sobre cómo ajustar este comportamiento predeterminado.

Importante

Aunque el acuerdo de desarrollador de Apple permite completamente las actualizaciones inalámbricas de JavaScript y los recursos (que es lo que habilita CodePush!), se aplica a su directiva para que una aplicación muestre un mensaje de actualización. Por este motivo, se recomienda que las aplicaciones distribuidas por App Store no habiliten la updateDialog opción al llamar a sync, mientras que Google Play y las aplicaciones distribuidas internamente (por ejemplo, Enterprise, Fabric, HockeyApp) pueden optar por habilitarla o personalizarla.

Publicación de actualizaciones

Una vez que la aplicación se ha configurado y distribuido a los usuarios, y ha realizado algunos cambios de código o recurso, es el momento de liberarlos al instante. La manera más sencilla (y recomendada) de hacerlo es usar el comando en la release-cordova CLI de CodePush, que controla la preparación y publicación de la actualización en el servidor CodePush.

Nota:

Para empezar a publicar actualizaciones, inicie sesión en App Center ejecutando el appcenter login comando .

En su forma más básica, este comando solo requiere un parámetro: el nombre del propietario + "/" + nombre de la aplicación.

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

Sugerencia

Al usar la función de la CLI set-current de App Center, no es necesario usar la marca -a para especificar la aplicación a la que se dirige un comando.

Sugerencia

Al publicar actualizaciones en CodePush, no necesitas aumentar la versión de la aplicación en el archivo config.xml , ya que no estás modificando la versión binaria en absoluto. Solo tiene que aumentar esta versión al actualizar Cordova o uno de los complementos, en cuyo momento debe publicar una actualización en los almacenes nativos. CodePush generará automáticamente una "etiqueta" para cada versión que realice (por ejemplo v3, ) para ayudar a identificarla en el historial de versiones.

El release-cordova comando habilita un flujo de trabajo tan sencillo porque comprende el diseño estándar de una aplicación cordova, por lo que puede generar la actualización y saber exactamente qué archivos cargar. Además, para admitir estrategias de versión flexibles, el release-cordova comando expone numerosos parámetros opcionales que le permiten personalizar cómo se debe distribuir la actualización a los usuarios finales (por ejemplo, ¿Qué versiones binarias son compatibles con ella? ¿Debe verse la versión como obligatoria?).

# 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

El cliente CodePush admite actualizaciones diferenciales, por lo que aunque publique el código de la aplicación en cada actualización, los usuarios finales solo descargarán realmente los archivos que necesitan. El servicio controla esto automáticamente para que pueda centrarse en la creación de aplicaciones impresionantes y podemos preocuparnos de optimizar las descargas del usuario final.

Para obtener más información sobre cómo funciona el release-cordova comando, así como los distintos parámetros que expone, consulte la documentación de la CLI. Además, si prefiere controlar la ejecución del cordova prepare comando usted mismo, por lo que quiere una solución aún más flexible que release-cordova, consulte el release comando para obtener más detalles.

Si tiene algún problema o tiene alguna pregunta, comentarios o comentarios, puede enviarnos un correo electrónico o abrir un nuevo problema en este repositorio y responderemos AAP. Consulte también ayuda y comentarios.

Referencia de la API

La API CodePush se expone a la aplicación a través del objeto global codePush , que está disponible después de que se active el deviceready evento. Esta API expone los siguientes métodos de nivel superior:

  • checkForUpdate: pregunta al servicio CodePush si la implementación de la aplicación configurada tiene disponible una actualización.
  • getCurrentPackage: recupera los metadatos sobre la actualización instalada actualmente (por ejemplo, descripción, tiempo de instalación, tamaño).
  • getPendingPackage: recupera los metadatos de una actualización (si existe) que se descargó e instaló, pero aún no se ha aplicado a través de un reinicio.
  • notifyApplicationReady: notifica al tiempo de ejecución de CodePush que una actualización instalada se considera correcta. Si busca e instala actualizaciones manualmente (es decir, no usa el método de sincronización para controlarlo todo), se debe llamar a este método; de lo contrario, CodePush tratará la actualización como con errores y revertirá a la versión anterior cuando se reinicie la aplicación.
  • restartApplication: reinicia inmediatamente la aplicación. Si hay una actualización pendiente, se mostrará inmediatamente al usuario final.
  • sync: permite comprobar una actualización, descargarla e instalarla, todo ello con una sola llamada. A menos que necesite una interfaz de usuario o un comportamiento personalizados, se recomienda que la mayoría de los desarrolladores usen este método al integrar CodePush en sus aplicaciones.

Además, los siguientes objetos y enumeraciones también se exponen globalmente como parte de codePush API:

codePush.checkForUpdate

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

Consulta el servicio CodePush para ver si la implementación de la aplicación configurada tiene disponible una actualización. De forma predeterminada, usará la clave de implementación configurada en el archivo config.xml , pero puede invalidarla especificando un valor a través del parámetro opcional deploymentKey . Esto puede ser útil cuando desea "redirigir" dinámicamente a un usuario a una implementación específica, como permitir el "acceso anticipado" a través de un huevo de pascua o un modificador de configuración de usuario.

Cuando se complete la comprobación de actualización, desencadenará la onUpdateCheck devolución de llamada con uno de los dos valores posibles:

  1. null si no hay ninguna actualización disponible. Esto ocurre en los escenarios siguientes:
    • La implementación configurada no contiene ninguna versión, por lo que no hay nada que actualizar.
    • La versión más reciente dentro de la implementación configurada tiene como destino una versión binaria diferente a la que se está ejecutando actualmente (ya sea anterior o más reciente).
    • La aplicación que se está ejecutando actualmente ya tiene la versión más reciente de la implementación configurada, por lo que no necesita la versión de nuevo.
  2. Instancia RemotePackage de que representa una actualización disponible que se puede inspeccionar y descargar posteriormente.

Parámetros:

  • onSuccess: devolución de llamada invocada al recibir una respuesta correcta del servidor. La devolución de llamada recibe un único parámetro, que se describe anteriormente.
  • onError: devolución de llamada opcional que se invoca en caso de error. La devolución de llamada toma un parámetro de error, que contiene los detalles del error.
  • deploymentKey: clave de implementación opcional que invalida la configuración de config.xml .

Ejemplo de uso:

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 los metadatos sobre el "paquete" instalado actualmente (por ejemplo, descripción, tiempo de instalación). Esto puede ser útil para escenarios como mostrar un cuadro de diálogo "novedades?" después de aplicar una actualización o comprobar si hay una actualización pendiente que está esperando que se aplique a través de un reinicio o reanudación.

Cuando se complete la recuperación de actualizaciones, desencadenará la onSuccess devolución de llamada con uno de los dos valores posibles:

  1. null si la aplicación está ejecutando actualmente la página de inicio HTML desde el binario y no una actualización de CodePush. Esto ocurre en los escenarios siguientes:
    • El usuario final instaló el binario de la aplicación y aún tiene que instalar una actualización de CodePush.
    • El usuario final instaló una actualización del binario (por ejemplo, del almacén), que despejó las actualizaciones antiguas de CodePush y devolvió prioridad al binario.
  2. Instancia LocalPackage de que representa los metadatos de la actualización codePush que se está ejecutando actualmente.

Parámetros:

  • onSuccess: devolución de llamada que se invoca al recibir los metadatos sobre la actualización que se está ejecutando actualmente. La devolución de llamada recibe un único parámetro, que se describe anteriormente.
  • onError: devolución de llamada opcional que se invoca en caso de error. La devolución de llamada toma un parámetro de error, que contiene los detalles del error.

Uso de ejemplo:

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

Obtiene los metadatos de la actualización pendiente actualmente (si existe). Una actualización se considera "pendiente" si se ha descargado e instalado, pero aún no se ha aplicado a través de un reinicio de la aplicación. Una actualización solo podría estar en este estado si InstallMode.ON_NEXT_RESTART o InstallMode.ON_NEXT_RESUME se especificó al llamar a sync o LocalPackage.install, y la aplicación aún no se ha reiniciado o reanudado (respectivamente). Este método puede ser útil si desea determinar si hay una actualización pendiente y, a continuación, preguntar al usuario si desea reiniciar inmediatamente (a través codePush.restartApplicationde ) para aplicarlo.

Cuando se complete la recuperación de actualizaciones, desencadenará la onSuccess devolución de llamada con uno de los dos valores posibles:

  1. null Si la aplicación no tiene actualmente una actualización pendiente (por ejemplo, la aplicación ya está ejecutando la versión disponible más reciente).
  2. Instancia LocalPackage de que representa los metadatos de la actualización de CodePush pendiente actualmente.

Parámetros:

  • onSuccess: devolución de llamada que se invoca al recibir los metadatos sobre la actualización pendiente actualmente. La devolución de llamada recibe un único parámetro, que se describe anteriormente.
  • onError: devolución de llamada opcional que se invoca en caso de error. La devolución de llamada toma un parámetro de error, que contiene los detalles del error.

Uso de ejemplo:

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 tiempo de ejecución de CodePush que una actualización recién instalada debe considerarse correcta, por lo que no es necesario revertir automáticamente el lado cliente. Es obligatorio llamar a esta función en algún lugar del código de la agrupación actualizada. De lo contrario, cuando la aplicación se reinicie a continuación, el entorno de ejecución de CodePush asume que se ha producido un error en la actualización instalada y se revierte a la versión anterior. Este comportamiento existe para ayudar a garantizar que los usuarios finales no estén bloqueados por una actualización interrumpida.

Si usa la función y realiza la comprobación de actualizaciones en el inicio de la sync aplicación, no es necesario llamar notifyApplicationReady manualmente, ya sync que la llamará automáticamente. Este comportamiento existe debido a la suposición de que cuando sync se llama a en la aplicación representa una buena aproximación de un inicio correcto.

Parámetros:

  • notifySucceeded: devolución de llamada opcional invocada si el complemento se notificó correctamente.
  • notifyFailed: devolución de llamada opcional invocada si se produce un error al notificar el complemento.

codePush.restartApplication

codePush.restartApplication();

Reinicia inmediatamente la aplicación. Este método es para escenarios avanzados y es fundamentalmente útil cuando se cumplen las condiciones siguientes:

  1. La aplicación especifica un valor de modo de instalación de ON_NEXT_RESTART o ON_NEXT_RESUME al llamar a los sync métodos o LocalPackage.install . Esto no aplica la actualización hasta que la aplicación se reinicie (por el usuario final o el sistema operativo) o se reanude, por lo que la actualización no se mostrará inmediatamente al usuario final.
  2. Tiene un evento de usuario específico de la aplicación (por ejemplo, el usuario final volvió a la ruta principal de la aplicación) que le permite aplicar la actualización de forma discreta y, posiblemente, obtiene la actualización delante del usuario final antes de esperar hasta el siguiente reinicio o reanudación.

codePush.sync

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

Sincroniza el código y las imágenes de la aplicación con la versión más reciente de la implementación configurada. A diferencia del checkForUpdate método , que comprueba la presencia de una actualización y le permite controlar qué hacer a continuación, sync controla la comprobación de actualizaciones, la experiencia de descarga e instalación automáticamente.

Este método proporciona compatibilidad con dos "modos" diferentes (pero personalizables) para habilitar fácilmente las aplicaciones con requisitos diferentes:

  1. Modo silencioso (comportamiento predeterminado), que descarga automáticamente las actualizaciones disponibles y las aplica la próxima vez que se reinicie la aplicación (por ejemplo, el sistema operativo o el usuario final lo eliminaron o el dispositivo se ha reiniciado). De este modo, toda la experiencia de actualización es "silenciosa" para el usuario final, ya que no ve ningún aviso de actualización ni se reinicia la aplicación "sintética".
  2. El modo activo, que cuando hay una actualización disponible, solicita al usuario final permiso antes de descargarlo y, a continuación, aplica inmediatamente la actualización. Si se publicó una actualización con la marca obligatoria, el usuario final seguirá recibiendo una notificación sobre la actualización, pero no tendría la opción de omitirla.

Uso de ejemplo:

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

Sugerencia

Si desea decidir si comprueba o descarga una actualización disponible en función del nivel de batería del dispositivo del usuario final, las condiciones de red etcetera. A continuación, encapsula la llamada a la sincronización en una condición que garantiza que solo se llame cuando se desee.

Aunque el método de sincronización intenta facilitar la realización de actualizaciones silenciosas y activas con poca configuración, acepta los siguientes parámetros opcionales que permiten personalizar numerosos aspectos del comportamiento predeterminado mencionado anteriormente:

  • syncCallback: se llama cuando el proceso de sincronización pasa de una fase a otra en el proceso de actualización general. Se llama al método con un código de estado que representa el estado actual y puede ser cualquiera de los SyncStatus valores.
  • syncOptions: parámetro opcional SyncOptions que configura el comportamiento de la operación de sincronización.
  • downloadProgress: se llama periódicamente cuando se descarga una actualización disponible desde el servidor CodePush. Se llama al método con un DownloadProgress objeto , que contiene las dos propiedades siguientes:
    • totalBytes (número): número total de bytes que se espera que se reciban para esta actualización (es decir, el tamaño del conjunto de archivos que cambiaron de la versión anterior).
    • receivedBytes (Número): número de bytes descargados hasta ahora, que se pueden usar para realizar un seguimiento del progreso de la descarga.
  • syncErrback: se llama cuando se produce un error en cualquiera de los pasos internos de sincronización. Se llama al método con un objeto javascript Error estándar como primer argumento.

SyncOptions

Aunque el sync método intenta facilitar la realización de actualizaciones silenciosas y activas con poca configuración, acepta un objeto "options" que le permite personalizar numerosos aspectos del comportamiento predeterminado mencionado anteriormente:

  • deploymentKey (String): especifica la clave de implementación en la que desea consultar una actualización. De forma predeterminada, este valor se deriva del archivo de config.xml , pero esta opción le permite invalidarlo desde el lado del script si necesita usar dinámicamente una implementación diferente para una llamada específica a sync.
  • installMode (InstallMode): especifica cuándo quiere instalar actualizaciones opcionales (es decir, las que no están marcadas como obligatorias). Tiene como valor predeterminado InstallMode.ON_NEXT_RESTART. Consulte la referencia de InstallMode enumeración para obtener una descripción de las opciones disponibles y lo que hacen.
  • mandatoryInstallMode (InstallMode): especifica cuándo desea instalar actualizaciones marcadas como obligatorias. Tiene como valor predeterminado InstallMode.IMMEDIATE. Consulte la referencia de InstallMode enumeración para obtener una descripción de las opciones disponibles y lo que hacen.
  • minimumBackgroundDuration (Número): especifica el número mínimo de segundos para que la aplicación esté en segundo plano antes de reiniciar la aplicación. Esta propiedad solo se aplica a las actualizaciones que se instalan mediante InstallMode.ON_NEXT_RESUMEy pueden ser útiles para obtener la actualización delante de los usuarios finales antes, sin ser demasiado obtrusiva. El valor predeterminado es 0, que aplica la actualización inmediatamente después de un currículum, sin embargo, tiempo que estaba en segundo plano.
  • ignoreFailedUpdates (booleano): especifica si se debe omitir una actualización disponible si se instaló anteriormente y se revierte en el cliente (porque notifyApplicationReady no se llamó correctamente). Tiene como valor predeterminado true.
  • updateDialog (UpdateDialogOptions): un objeto "options" usado para determinar si se debe mostrar un cuadro de diálogo de confirmación al usuario final cuando haya una actualización disponible y, si es así, qué cadenas usar. El valor predeterminado es null, que deshabilita el cuadro de diálogo. Si se establece en cualquier true valor, se habilitará el cuadro de diálogo con las cadenas predeterminadas y se pasa un objeto a este parámetro, se permite habilitar el cuadro de diálogo, así como invalidar una o varias de las cadenas predeterminadas.

La lista siguiente representa las opciones disponibles y sus valores predeterminados:

  • appendReleaseDescription (booleano): indica si desea anexar la descripción de una versión disponible al mensaje de notificación que se muestra al usuario final. Tiene como valor predeterminado false.
  • descriptionPrefix (String): indica la cadena con la que desea prefijar la descripción de la versión, si existe, al mostrar la notificación de actualización al usuario final. Tiene como valor predeterminado " Description: ".
  • mandatoryContinueButtonLabel (String): el texto que se va a usar para el botón que el usuario final debe presionar para instalar una actualización obligatoria. Tiene como valor predeterminado "Continue".
  • mandatoryUpdateMessage (String): el texto usado como cuerpo de una notificación de actualización, cuando la actualización se especifica como obligatoria. Tiene como valor predeterminado "An update is available that must be installed.".
  • optionalIgnoreButtonLabel (String): el texto que se va a usar para el botón que el usuario final puede presionar para omitir una actualización opcional disponible. Tiene como valor predeterminado "Ignore".
  • optionalInstallButtonLabel (String): el texto que se va a usar para el botón que el usuario final puede presionar para instalar una actualización opcional. Tiene como valor predeterminado "Install".
  • optionalUpdateMessage (String): el texto usado como cuerpo de una notificación de actualización, cuando la actualización es opcional. Tiene como valor predeterminado "An update is available. Would you like to install it?". *- updateTitle (String): el texto usado como encabezado de una notificación de actualización que se muestra al usuario final. Tiene como valor predeterminado "Update available".

Uso de ejemplo:

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

Se sync puede llamar al método en cualquier lugar en el que quiera comprobar si hay una actualización. Esto podría estar en el deviceready controlador de eventos, el click evento de un botón, en la devolución de llamada de un temporizador periódico, o lo que tenga sentido para sus necesidades. Al igual que el checkForUpdate método , ejecutará la solicitud de red para comprobar si hay una actualización en segundo plano, por lo que no afectará a la capacidad de respuesta del subproceso de la interfaz de usuario o del subproceso de JavaScript.

Objetos de paquete

Los checkForUpdate métodos y getCurrentPackage invocan devoluciones de llamada correctas, que cuando se desencadenan, proporcionan acceso a objetos "package". El paquete representa la actualización del código, así como cualquier metadato adicional (por ejemplo, descripción, obligatorio?). CodePush API tiene la distinción entre los siguientes tipos de paquetes:

  1. LocalPackage: representa una actualización descargada que ya está en ejecución o que se ha instalado y está pendiente de reiniciar la aplicación.
  2. RemotePackage: representa una actualización disponible en el servidor CodePush que aún no se ha descargado.

LocalPackage

Contiene detalles sobre una actualización que se ha descargado localmente o que ya está instalada. Puede obtener una referencia a una instancia de este objeto llamando al codePush.getCurrentPackage método o como el valor proporcionado a la devolución de llamada correcta del RemotePackage.download método .

Propiedades
  • appVersion: la versión nativa de la aplicación para la que está pensada esta actualización de paquete. (String)
  • deploymentKey: clave de implementación del paquete. (String)
  • description: descripción de la actualización. Este es el mismo valor que especificó en la CLI al publicar la actualización. (String)
  • failedInstall: indica si esta actualización se instaló anteriormente, pero se reviertó. El sync método omitirá automáticamente las actualizaciones que han producido un error anteriormente, por lo que solo debe preocuparse por esta propiedad si usa checkForUpdate. (Boolean)
  • isFirstRun: marca que indica si la ejecución de la aplicación actual es la primera después de aplicar el paquete. (Boolean)
  • isMandatory: indica si la actualización se considera obligatoria. Este es el valor que se especificó en la CLI cuando se publicó la actualización. (Boolean)
  • label: la etiqueta interna dada automáticamente a la actualización por el servidor CodePush, como v5. Este valor identifica de forma única la actualización dentro de su implementación. (String)
  • packageHash: valor hash sha de la actualización. (String)
  • packageSize: tamaño del código contenido en la actualización, en bytes. (Número)
Métodos
  • install(installSuccess, installError, installOptions): instala este paquete en la aplicación. El comportamiento de instalación depende del proporcionado installOptions. De forma predeterminada, el paquete de actualización se instala de forma silenciosa y la aplicación se vuelve a cargar con el nuevo contenido en el siguiente inicio de la aplicación. En la primera ejecución después de la actualización, la aplicación esperará una codePush.notifyApplicationReady() llamada. Una vez realizada esta llamada, la operación de instalación se considera correcta. De lo contrario, la operación de instalación se marcará como errónea y la aplicación se revertirá a su versión anterior en la siguiente ejecución.
InstallOptions

Interfaz que define varias opciones para personalizar el comportamiento de la operación de instalación.

  • installMode: se usa para especificar installMode usado para la operación de instalación. Tiene como valor predeterminado InstallMode.ON_NEXT_RESTART.
  • mandatoryInstallMode: se usa para especificar installMode usado para la operación de instalación si el paquete es obligatorio. Tiene como valor predeterminado InstallMode.IMMEDIATE.
  • minimumBackgroundDuration: si installMode es InstallMode.ON_NEXT_RESUME, se usa para especificar la cantidad de tiempo que la aplicación debe estar en segundo plano antes de instalar la actualización cuando se reanude. Tiene como valor predeterminado 0.

Uso de ejemplo:

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

Para obtener un ejemplo sobre cómo está protegido frente a una actualización incorrecta, consulte la documentación de notifyApplicationReady().

RemotePackage

Contiene detalles sobre una actualización que está disponible para su descarga desde el servidor CodePush. Para obtener una referencia a una instancia de este objeto, llame al codePush.checkForUpdate método cuando haya una actualización disponible. Si usa la API de sincronización, no es necesario preocuparse por RemotePackage, ya que controlará automáticamente el proceso de descarga e instalación.

Propiedades

RemotePackage Hereda todas las mismas propiedades que , LocalPackagepero incluye una adicional:

  • downloadUrl: la dirección URL en la que el paquete está disponible para su descarga. Esta propiedad solo es necesaria para el uso avanzado, ya que el download método controlará automáticamente la adquisición de actualizaciones automáticamente. (String)
Métodos
  • abortDownload(abortSuccess, abortError): anula la sesión de descarga actual, si existe.
  • download(downloadSuccess, downloadError, downloadProgress): descarga la actualización del paquete desde el servicio CodePush. La downloadSuccess devolución de llamada se invoca con un argumento LocalPackage , que representa el paquete descargado. La devolución de llamada opcional downloadProgress se invoca varias veces durante el progreso de la descarga con un DownloadProgress parámetro.
DownloadProgress

Define el formato del objeto DownloadProgress, que se usa para enviar notificaciones de actualización periódicas en el progreso de la descarga de la actualización.

Propiedades
  • totalBytes: tamaño del paquete de actualización de descarga, en bytes. (Número)
  • receivedBytes: número de bytes que ya se han descargado. (Número)

Uso de ejemplo:

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

Enumeraciones

La API CodePush incluye los siguientes objetos de "enumeración" que se pueden usar para personalizar la experiencia de actualización y están disponibles globalmente fuera del window objeto:

InstallMode

Esta enumeración especificó cuando desea que se aplique realmente una actualización instalada y se puede pasar a los sync métodos o LocalPackage.install . Incluye los siguientes valores:

  • IMMEDIATE: la actualización se aplicará inmediatamente a la aplicación en ejecución. La aplicación se volverá a cargar con el nuevo contenido inmediatamente.
  • ON_NEXT_RESTART: indica que desea instalar la actualización, pero no reiniciar la aplicación de forma forzada. Cuando la aplicación se reinicia de forma natural (debido al sistema operativo o al usuario final que lo mata), la actualización se recogerá sin problemas. Este valor es adecuado al realizar actualizaciones silenciosas, ya que es probable que sea perjudicial para el usuario final si la aplicación se reinicia repentinamente fuera de ninguna parte, ya que no habrían realizado una actualización incluso se descargó. Este es el modo predeterminado que se usa para los sync métodos y LocalPackage.install .

Para obtener un ejemplo sobre cómo está protegido frente a una actualización incorrecta, consulte la documentación de notifyApplicationReady().

RemotePackage

Contiene detalles sobre una actualización que está disponible para su descarga desde el servidor CodePush. Para obtener una referencia a una instancia de este objeto, llame al codePush.checkForUpdate método cuando haya una actualización disponible. Si usa la API de sincronización, no es necesario preocuparse por RemotePackage, ya que controlará automáticamente el proceso de descarga e instalación.

Propiedades

RemotePackage Hereda todas las mismas propiedades que , LocalPackagepero incluye una adicional:

  • downloadUrl: la dirección URL en la que el paquete está disponible para su descarga. Esta propiedad solo es necesaria para el uso avanzado, ya que el download método controlará automáticamente la adquisición de actualizaciones automáticamente. (String)
Métodos
  • abortDownload(abortSuccess, abortError): anula la sesión de descarga actual, si existe.
  • download(downloadSuccess, downloadError, downloadProgress): descarga la actualización del paquete desde el servicio CodePush. La downloadSuccess devolución de llamada se invoca con un argumento LocalPackage , que representa el paquete descargado. La devolución de llamada opcional downloadProgress se invoca varias veces durante el progreso de la descarga con un DownloadProgress parámetro.
DownloadProgress

Define el formato del objeto DownloadProgress, que se usa para enviar notificaciones de actualización periódicas en el progreso de la descarga de la actualización.

Propiedades de #
  • totalBytes: tamaño del paquete de actualización de descarga, en bytes. (Número)
  • receivedBytes: número de bytes que ya se han descargado. (Número)

Uso de ejemplo:

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

Enumeraciones

La API CodePush incluye los siguientes objetos de "enumeración" que se pueden usar para personalizar la experiencia de actualización y están disponibles globalmente fuera del window objeto:

InstallMode

Esta enumeración especificó cuando desea que se aplique realmente una actualización instalada y se puede pasar a los sync métodos o LocalPackage.install . Incluye los siguientes valores:

  • IMMEDIATE: la actualización se aplicará inmediatamente a la aplicación en ejecución. La aplicación se volverá a cargar con el nuevo contenido inmediatamente.
  • ON_NEXT_RESTART: indica que desea instalar la actualización, pero no reiniciar la aplicación de forma forzada. Cuando la aplicación se reinicia de forma natural (debido al sistema operativo o al usuario final que lo mata), la actualización se recogerá sin problemas. Este valor es adecuado al realizar actualizaciones silenciosas, ya que es probable que sea perjudicial para el usuario final si la aplicación se reinicia repentinamente fuera de ninguna parte, ya que no habrían realizado una actualización incluso se descargó. Este es el modo predeterminado que se usa para los sync métodos y LocalPackage.install .
  • ON_NEXT_RESUME: indica que desea instalar la actualización, pero no desea reiniciar la aplicación hasta la próxima vez que el usuario final lo reanude desde segundo plano. De este modo, no interrumpe su sesión actual, pero puede obtener la actualización delante de ellas antes de tener que esperar al siguiente reinicio natural. Este valor es adecuado para las instalaciones silenciosas que se pueden aplicar al reanudar de forma no invasiva.

SyncStatus

Define los posibles estados de la operación de sincronización . Hay dos categorías de estados: intermedio y resultado (final). Los estados intermedios representan los estados de progreso de la operación de sincronización y no son finales. Los estados de resultado representan los estados finales de la operación de sincronización. Cada operación de sincronización finaliza con un solo estado de resultado, pero puede tener cero o más estados intermedios.

  • UP_TO_DATE: la aplicación está totalmente actualizada con la implementación configurada.
  • UPDATE_INSTALLED: se ha instalado una actualización disponible y se ejecutará inmediatamente después de que la función de devolución de llamada se devuelva o la próxima vez que la aplicación se reanude o reinicie, en función del InstallMode especificado en SyncOptions.
  • UPDATE_IGNORED: la aplicación tiene una actualización opcional, que el usuario final eligió omitir. (Esto solo es aplicable cuando se usa )updateDialog
  • ERROR: error durante la sync operación. Esto puede ser un error al comunicarse con el servidor, descargando o descomprimiendo la actualización. Los registros de consola deben contener más información sobre lo que ha ocurrido. No se ha aplicado ninguna actualización en este caso.
  • IN_PROGRESS: ya se está ejecutando otra sincronización, por lo que este intento de sincronización se ha anulado.
  • CHECKING_FOR_UPDATE: el servidor CodePush se está consultando para obtener una actualización.
  • AWAITING_USER_ACTION: hay disponible una actualización y se ha mostrado un cuadro de diálogo de confirmación al usuario final. (Esto solo es aplicable cuando se usa )updateDialog
  • DOWNLOADING_PACKAGE: se descarga una actualización disponible desde el servidor CodePush.
  • INSTALLING_UPDATE: se descargó una actualización disponible y está a punto de instalarse.

Compilación de PhoneGap

Este complemento es compatible con PhoneGap Build y admite la creación de compilaciones de Android e iOS integradas. Sin embargo, para que CodePush calcule el hash del contenido binario en Android, PhoneGap Build debe usar Gradle para compilar la aplicación, que no es su comportamiento predeterminado (usa Ant). Para resolverlo, agregue el siguiente elemento al archivo config.xml del proyecto, como elemento secundario del <platform name="android"> elemento :

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

Aplicaciones de ejemplo

La comunidad de Cordova ha creado con gracia algunas aplicaciones de código abierto impresionantes que pueden servir como ejemplos para los desarrolladores que se están iniciando. La siguiente lista es de las aplicaciones cordova del sistema operativo que también usan CodePush y se pueden usar para ver cómo otros usan el servicio:

Nota:

Si ha desarrollado una aplicación cordova con CodePush, es de código abierto, háganoslo saber. ¡Nos encantaría agregarlo a esta lista!