Поделиться через

Пакет SDK для клиента Cordova

  • Статья

Внимание

Центр приложений Visual Studio планируется выйти на пенсию 31 марта 2025 г. Хотя вы можете продолжать использовать Центр приложений Visual Studio до тех пор, пока он не будет полностью прекращен, существует несколько рекомендуемых вариантов, которые можно перенести.

Дополнительные сведения о временной шкале поддержки и альтернативах.

Этот подключаемый модуль обеспечивает интеграцию на стороне клиента для службы CodePush, что позволяет легко добавлять динамические обновления в приложения Cordova.

Примечание.

Поддержка Cordova Apps закончилась в апреле 2022 года. Дополнительные сведения см. в блоге Центра приложений.

Как это работает?

Приложение Cordova состоит из ФАЙЛОВ HTML, CSS и JavaScript и всех сопровождающих изображений, которые объединяются cli Cordova и распределяются как часть двоичного файла для конкретной платформы (т. е. ipa или .apk-файла). После выпуска приложения обновление кода или ресурсов образа требует повторной компиляции и распространения всего двоичного файла. Этот процесс включает время проверки для магазинов, в которые вы публикуете.

Подключаемый модуль CodePush помогает мгновенно получать улучшения продукта перед конечными пользователями, сохраняя код и изображения, синхронизированные с обновлениями, выпущенными на сервер CodePush. Таким образом, ваше приложение получает преимущества автономного мобильного интерфейса, а также гибкость веб-приложений при загрузке обновлений на стороне, как только они будут доступны. Это беспроигрышный вариант.

Чтобы конечные пользователи всегда имели функционирующую версию приложения, подключаемый модуль CodePush поддерживает копию предыдущего обновления, чтобы в случае случайной отправки обновления, включающего сбой, он может автоматически откатить. Таким образом, вы можете убедиться, что ваша новая гибкость выпуска не приведет к блокировке пользователей, прежде чем у вас есть возможность откатить на сервере. Это выиграть победу!

Примечание.

Любые изменения продукта, касающиеся машинного кода (например, обновление версий Cordova, добавление нового подключаемого модуля) не могут распространяться через CodePush, и поэтому их необходимо обновить с помощью соответствующих магазинов.

Поддерживаемые платформы Cordova

Cordova 5.0.0+ полностью поддерживается вместе со следующими связанными платформами:

  • Android (cordova-android 4.0.0+) - включая кроссуайт!
  • iOS (cordova-ios 3.9.0+) — (Чтобы использовать CodePush вместе с cordova-plugin-wkwebview-engine подключаемым модулем, необходимо установить v1.5.1-beta+, которая включает полную поддержку приложений с помощью WebView.)

Чтобы проверить версии каждой платформы Cordova, которую вы используете в настоящее время, можно выполнить следующую команду и проверить Installed platforms список:

    cordova platform ls

Если вы используете более старую платформу Android или iOS, чем упоминалось выше, и будете открыты для обновления, это можно сделать, выполнив следующие команды (опустив платформу, если это не требуется):

    cordova platform update android
    cordova platform update ios

Начало работы

Примечание.

Эта статья содержит ссылки на термин список разрешений. Корпорация Майкрософт больше не использует его. Когда этот термин будет удален из программного обеспечения, мы удалим его из статьи.

Следуя инструкциям по настройке учетной записи CodePush, вы можете запустить CodePush-ifying приложение Cordova, выполнив следующую команду из корневого каталога приложения:

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

Установив подключаемый модуль CodePush, настройте приложение для его использования с помощью следующих действий:

  1. Добавьте ключи развертывания в файл config.xml , чтобы включить правильный ключ для каждой платформы 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>

Как напоминание, эти ключи создаются при создании приложения CodePush с помощью интерфейса командной строки. Если вам нужно получить их, можно запустить appcenter codepush deployment list -a <ownerName>/<appName> --displayKeysи захватить ключ для конкретного развертывания, которое вы хотите использовать (напримерStaging, ). Production

Внимание

Мы рекомендуем создать отдельное приложение CodePush для iOS и Android, поэтому приведенный выше пример объявляет отдельные ключи для Android и iOS. Если вы разрабатываете только для одной платформы, необходимо указать только ключ развертывания для Android или iOS, поэтому вам не нужно добавить дополнительный <platform> элемент, как показано выше.

Начиная с версии 1.10.0 вы можете подписать пакеты обновлений (дополнительные сведения о подписи кода см. в соответствующем разделе документации). Чтобы включить подпись кода для приложения Cordova, необходимо настроить открытый ключ для проверки подписи пакета, указав следующий preference параметр:config.xml

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

Для каждой платформы можно использовать одну пару закрытых и открытых ключей.

  1. Если вы используете <access origin="*" /> элемент в файле config.xml , приложение уже может взаимодействовать с серверами CodePush, и вы можете безопасно пропустить этот шаг. В противном случае добавьте следующие дополнительные <access /> элементы:
    <access origin="https://codepush.appcenter.ms" />
    <access origin="https://codepush.blob.core.windows.net" />
    <access origin="https://codepushupdates.azureedge.net" />
  1. Чтобы убедиться, что приложение может получить доступ к серверу CodePush на платформах, совместимых с CSP, добавьте meta https://codepush.appcenter.ms Content-Security-Policy в тег в index.html файле:
    <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. Наконец, дважды проверьте, установлен ли подключаемый cordova-plugin-whitelist модуль (большинство приложений). Чтобы проверить это, выполните следующую команду:
    cordova plugin ls

Если cordova-plugin-whitelist вы находитесь в списке, то вы хороши, чтобы пойти. В противном случае выполните следующую команду, чтобы добавить ее:

    cordova plugin add cordova-plugin-whitelist

Теперь вы готовы использовать подключаемый модуль в коде приложения. Дополнительные сведения см. в примерах приложений и документации по API.

Использование подключаемого модуля

При установке и настройке подключаемого модуля CodePush единственное, что осталось, — добавить необходимый код в приложение для управления следующими политиками:

  1. Когда (и как часто) проверить наличие обновления? (e.g. app начать, в ответ на нажатие кнопки на странице параметров периодически с определенным фиксированным интервалом)
  2. Когда доступно обновление, как представить его конечному пользователю? Самый простой способ сделать это — выполнить следующее в обработчике событий приложения deviceready :
codePush.sync();

Если обновление доступно, оно будет автоматически загружено и установлено при следующем перезапуске приложения (явным образом конечным пользователем или операционной системой), что обеспечивает наименее инвазивный интерфейс для конечных пользователей. Если доступное обновление является обязательным, оно будет установлено немедленно, гарантируя, что конечный пользователь получит его как можно скорее.

Если вы хотите, чтобы приложение было быстрее обнаруживать обновления, вы также можете вызывать sync каждый раз, когда приложение возобновляется из фонового режима, добавив следующий код (или эквивалентный) в рамках поведения запуска приложения. Вы можете звонить sync так часто, как вы хотите, поэтому когда и где вы звоните, зависит от вашего личного предпочтения.

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

Кроме того, если вы хотите отобразить диалоговое окно подтверждения обновления (активная установка), настройте, когда доступное обновление (например, принудительно перезапустить) или настроить интерфейс обновления каким-либо образом, обратитесь sync к справочнику по API метода для получения сведений о том, как настроить это поведение по умолчанию.

Внимание

В то время как соглашение разработчика Apple полностью разрешает обновления JavaScript и ресурсов (что позволяет CodePush!), это против их политики, чтобы приложение отображало запрос на обновление. Из-за этого рекомендуется, чтобы распределенные приложения App Store не разрешали updateDialog возможность вызова sync, а Google Play и внутренние распределенные приложения (например, Enterprise, Fabric, HockeyApp) могут включить или настроить его.

Выпуск обновлений

После настройки и распространения приложения пользователями, и вы внесли некоторые изменения в код или ресурс, пришло время мгновенно освободить их! Самый простой (и рекомендуемый) способ сделать это — использовать release-cordova команду в CLI CodePush, которая обрабатывает подготовку и выпуск обновления на сервер CodePush.

Примечание.

Прежде чем начать выпуск обновлений, войдите в Центр приложений, выполнив команду.appcenter login

В самой базовой форме эта команда требует только одного параметра: имя владельца + "/" + имя приложения.

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

Совет

Используя функцию CLI set-current Центра приложений, вам не нужно использовать флаг -a, чтобы указать приложение, на которое направлена команда.

Совет

При выпуске обновлений в CodePush вам не нужно ударить версию приложения в файле config.xml , так как вы не изменяете двоичную версию вообще. При обновлении Cordova или одного из подключаемых модулей вам потребуется обновить эту версию только в том случае, когда необходимо освободить обновление для собственных магазинов. CodePush автоматически создает метку для каждого выпуска, который вы делаете (например v3, чтобы помочь определить его в журнале выпусков).

Эта release-cordova команда включает такой простой рабочий процесс, так как он понимает стандартный макет приложения Cordova, и поэтому может создать обновление и точно знать, какие файлы нужно отправить. Кроме того, для поддержки гибких release-cordova стратегий выпуска команда предоставляет множество необязательных параметров, которые позволяют настроить способ распространения обновления для конечных пользователей (например, какие двоичные версии совместимы с ним? Должен ли выпуск рассматриваться как обязательный?).

# 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

Клиент CodePush поддерживает разностные обновления, поэтому даже если вы выпускаете код приложения при каждом обновлении, конечные пользователи будут загружать только необходимые файлы. Служба обрабатывает это автоматически, чтобы вы могли сосредоточиться на создании удивительных приложений, и мы можем беспокоиться о оптимизации загрузки конечных пользователей.

Дополнительные сведения о release-cordova работе команды, а также о различных параметрах, предоставляемых им, см. в документации по CLI. Кроме того, если вы предпочитаете обрабатывать cordova prepare команду самостоятельно, и поэтому требуется еще более гибкое решение, чемrelease release-cordovaкоманда, дополнительные сведения см. в этой команде.

Если у вас возникли проблемы или возникли какие-либо вопросы, комментарии и отзывы, вы можете отправить нам электронную почту или открыть новую проблему в этом репозитории, и мы ответим asap! См. также справку и отзывы.

Справочник по API

API CodePush предоставляется приложению через глобальный codePush объект, который доступен после срабатывания deviceready события. Этот API предоставляет следующие методы верхнего уровня:

  • checkForUpdate: запрашивает службу CodePush, доступно ли настроенное развертывание приложения.
  • getCurrentPackage: извлекает метаданные об установленном обновлении (например, описание, время установки, размер).
  • getPendingPackage: извлекает метаданные для обновления (если он существует), скачанный и установленный, но еще не применен через перезапуск.
  • notifyApplicationReady: уведомляет среду выполнения CodePush о том, что установленное обновление считается успешным. Если вы вручную проверяете наличие и установку обновлений (т. е. не используете метод синхронизации для обработки всех для вас), то этот метод должен вызываться; в противном случае CodePush будет обрабатывать обновление как сбой и откатить к предыдущей версии при следующем перезапуске приложения.
  • restartApplication: немедленно перезапускает приложение. Если ожидается обновление, оно будет немедленно отображаться для конечного пользователя.
  • синхронизация: позволяет проверять обновление, скачивание и установку его, все с одним вызовом. Если вам не нужен пользовательский интерфейс или поведение, мы рекомендуем большинству разработчиков использовать этот метод при интеграции CodePush в свои приложения.

Кроме того, следующие объекты и перечисления также предоставляются глобально в рамках API CodePush:

  • InstallMode: определяет доступные режимы установки для обновлений.
  • LocalPackage: содержит сведения о локально установленном пакете.
  • RemotePackage: содержит сведения о пакете обновления, доступном для скачивания.
  • SyncStatus: определяет возможные промежуточные и результирующий состояния операции синхронизации .

codePush.checkForUpdate

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

Запрашивает службу CodePush, чтобы узнать, доступно ли настроенное развертывание приложения. По умолчанию он будет использовать ключ развертывания, настроенный в файле config.xml , но его можно переопределить, указав значение с помощью необязательного deploymentKey параметра. Это может быть полезно, если вы хотите динамически перенаправить пользователя в определенное развертывание, например разрешить "Ранний доступ" через пасхальное яйцо или переключатель параметров пользователя.

После завершения проверки обновления обратный вызов будет запускаться onUpdateCheck с одним из двух возможных значений:

  1. null Если обновление недоступно. Это происходит в следующих сценариях:
    • Настроенное развертывание не содержит выпусков, поэтому обновление не требуется.
    • Последний выпуск в настроенном развертывании предназначен для другой двоичной версии, отличной от используемой в данный момент версии (более старой или более новой).
    • В настоящее время работающее приложение уже имеет последний выпуск из настроенного развертывания, поэтому он не нуждается в выпуске еще раз.
  2. RemotePackage Экземпляр, представляющий доступное обновление, которое можно проверить и загрузить позже.

Параметры:

  • onSuccess: обратный вызов, который вызывается при получении успешного ответа от сервера. Обратный вызов получает один параметр, описанный выше.
  • onError: необязательный обратный вызов, который вызывается в случае ошибки. Обратный вызов принимает один параметр ошибки, содержащий сведения об ошибке.
  • deploymentKey: необязательный ключ развертывания, который переопределяет параметр config.xml .

Пример использования:

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

Извлекает метаданные о текущем установленном пакете (например, описании, времени установки). Это может быть полезно для таких сценариев, как отображение диалогового окна "Что нового?" после применения обновления или проверки наличия ожидающего обновления, ожидающего применения с помощью возобновления или перезапуска.

После завершения извлечения обновления вызов будет активирован onSuccess с одним из двух возможных значений:

  1. null Значение , если приложение в настоящее время выполняет начальную страницу HTML из двоичного файла, а не обновление CodePush. Это происходит в следующих сценариях:
    • Конечный пользователь установил двоичный файл приложения и еще не установил обновление CodePush
    • Конечный пользователь установил обновление двоичного файла (например, из хранилища), которое очистило старые обновления CodePush и дало приоритет двоичному файлу.
  2. LocalPackage Экземпляр, представляющий метаданные для текущего обновления CodePush.

Параметры:

  • onSuccess: обратный вызов, который вызывается при получении метаданных о текущем обновлении. Обратный вызов получает один параметр, описанный выше.
  • onError: необязательный обратный вызов, который вызывается в случае ошибки. Обратный вызов принимает один параметр ошибки, содержащий сведения об ошибке.

Пример использования:

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

Возвращает метаданные для текущего ожидающего обновления (если он существует). Обновление считается "ожидаемым", если оно загружено и установлено, но еще не было применено через перезапуск приложения. Обновление может находиться только в этом состоянии, если InstallMode.ON_NEXT_RESTART или InstallMode.ON_NEXT_RESUME было указано при вызове sync или LocalPackage.install, а приложение еще не было перезапущено или возобновлено (соответственно). Этот метод может быть полезен, если вы хотите определить, существует ли ожидающее обновление, а затем предложите пользователю немедленно перезапустить (через codePush.restartApplication) применить его.

После завершения извлечения обновления вызов будет активирован onSuccess с одним из двух возможных значений:

  1. null Если в настоящее время приложение не имеет ожидающего обновления (например, приложение уже выполняет последнюю доступную версию).
  2. LocalPackage Экземпляр, представляющий метаданные для текущего ожидающего обновления CodePush.

Параметры:

  • onSuccess: обратный вызов, который вызывается при получении метаданных об ожидающих обновлении в настоящее время. Обратный вызов получает один параметр, описанный выше.
  • onError: необязательный обратный вызов, который вызывается в случае ошибки. Обратный вызов принимает один параметр ошибки, содержащий сведения об ошибке.

Пример использования:

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

Уведомляет среду выполнения CodePush о том, что недавно установленное обновление должно считаться успешным, поэтому автоматическое откат на стороне клиента не требуется. Необходимо вызвать эту функцию где-то в коде обновленного пакета. В противном случае при следующем перезапуске приложения среда выполнения CodePush предполагает, что установленное обновление завершилось сбоем и откатится к предыдущей версии. Это поведение помогает гарантировать, что конечные пользователи не блокируются сломанным обновлением.

Если вы используете sync функцию и выполняете проверку обновления при запуске приложения, вам не нужно вручную notifyApplicationReady sync вызывать ее. Это поведение существует из-за предположения, что при sync вызове в приложении представляется хорошее приближение успешного запуска.

Параметры:

  • notifySucceeded: необязательный обратный вызов вызывается, если подключаемый модуль успешно уведомлен.
  • notifyFailed: необязательный обратный вызов вызывается, если возникает ошибка, уведомляющая подключаемый модуль.

codePush.restartApplication

codePush.restartApplication();

Немедленно перезапускает приложение. Этот метод предназначен для расширенных сценариев и в первую очередь полезен при выполнении следующих условий:

  1. Приложение задает значение ON_NEXT_RESTART режима установки или ON_NEXT_RESUME при вызове sync методов или LocalPackage.install методов. Это не применяет обновление, пока приложение не перезагрузится (конечным пользователем или ОС) или возобновляет работу, поэтому обновление не будет немедленно отображаться для конечного пользователя.
  2. У вас есть событие пользователя для конкретного приложения (например, конечный пользователь вернулся к домашнему маршруту приложения), которое позволяет применить обновление ненавязчивым способом, и потенциально получает обновление перед конечным пользователем раньше, чем ждать, пока следующий перезапуск или возобновление.

codePush.sync

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

Синхронизирует код и образы приложения с последним выпуском с настроенным развертыванием. checkForUpdate В отличие от метода, который проверяет наличие обновления и позволяет управлять тем, что делать дальше, обрабатывает проверку обновления, sync скачивание и установку для вас.

Этот метод обеспечивает поддержку двух разных (но настраиваемых) "режимов", чтобы легко включить приложения с различными требованиями:

  1. Автоматический режим (поведение по умолчанию), который автоматически скачивает доступные обновления и применяет их при следующем перезапуске приложения (например, ОС или конечного пользователя, или устройство было перезапущено). Таким образом, весь интерфейс обновления "безмолвный" для конечного пользователя, так как они не видят никаких запросов на обновление или "синтетических" перезапусков приложений.
  2. Активный режим, который, когда обновление доступно, запрашивает пользователю разрешение перед загрузкой, а затем немедленно применяет обновление. Если обновление было выпущено с помощью обязательного флага, конечный пользователь по-прежнему будет получать уведомления об обновлении, но у них не будет выбора игнорировать его.

Пример использования:

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

Совет

Если вы хотите решить, проверяете или скачиваете доступное обновление на основе уровня заряда устройства конечного пользователя, состояния сети и т. д., а затем заключите вызов для синхронизации в условии, которое гарантирует, что он будет вызываться только при необходимости.

Хотя метод синхронизации пытается упростить автоматическое и активное обновление с небольшой конфигурацией, он принимает следующие необязательные параметры, которые позволяют настроить многочисленные аспекты поведения по умолчанию, указанного выше:

  • syncCallback: вызывается при переходе процесса синхронизации с одного этапа на другой в общем процессе обновления. Метод вызывается с кодом состояния, который представляет текущее состояние и может быть любым из значений SyncStatus .
  • syncOptions: необязательный SyncOptions параметр, который настраивает поведение операции синхронизации.
  • downloadProgress: периодически вызывается, когда доступное обновление загружается с сервера CodePush. Метод вызывается с DownloadProgress объектом, который содержит следующие два свойства:
    • totalBytes (Number) — общее число байтов, которое должно быть получено для этого обновления (т. е. размер набора файлов, измененных с предыдущего выпуска).
    • receivedBytes (Number) — количество скачанных байтов до сих пор, которое можно использовать для отслеживания хода скачивания.
  • syncErrback: вызывается при возникновении ошибки во всех внутренних шагах синхронизации. Метод вызывается с помощью стандартного объекта javascript Error в качестве первого аргумента.

SyncOptions

sync Хотя метод пытается упростить автоматическое и активное обновление с небольшой конфигурацией, он принимает объект options, который позволяет настроить многочисленные аспекты поведения по умолчанию, указанного выше:

  • deploymentKey (String) — указывает ключ развертывания, для которого требуется запросить обновление. По умолчанию это значение является производным от файла config.xml, но этот параметр позволяет переопределить его на стороне скрипта, если необходимо динамически использовать другое развертывание для конкретного вызоваsync.
  • installMode (InstallMode) — указывает, когда требуется установить необязательные обновления (т. е. те, которые не помечены как обязательные). По умолчанию — InstallMode.ON_NEXT_RESTART. Ознакомьтесь со ссылкой на перечисление InstallMode для описания доступных параметров и того, что они делают.
  • обязательный атрибутInstallMode (InstallMode) — указывает, когда требуется установить обновления, помеченные как обязательные. По умолчанию — InstallMode.IMMEDIATE. Ознакомьтесь со ссылкой на перечисление InstallMode для описания доступных параметров и того, что они делают.
  • minimumBackgroundDuration (Number) — указывает минимальное количество секунд для приложения, которое должно находиться в фоновом режиме перед перезапуском приложения. Это свойство применяется только к обновлениям, установленным с помощью InstallMode.ON_NEXT_RESUME, и может быть полезно для получения обновления перед конечными пользователями раньше, не будучи слишком навязчивым. По 0умолчанию применяется обновление сразу после возобновления, однако долгое время оно было в фоновом режиме.
  • ignoreFailedUpdates (boolean) — указывает, следует ли игнорировать доступное обновление, если оно было установлено и откатено на клиенте (так как notifyApplicationReady не было успешно вызвано). По умолчанию — true.
  • updateDialog (UpdateDialogOptions) — объект options, используемый для определения того, следует ли отображать диалоговое окно подтверждения для конечного пользователя, когда доступно обновление, и если да, какие строки следует использовать. Значение nullпо умолчанию, которое отключает диалоговое окно. При задании этого true значения диалоговое окно будет включать строки по умолчанию и передавать объект этому параметру, что позволяет включить диалоговое окно, а также переопределить одну или несколько строк по умолчанию.

Следующий список представляет доступные параметры и их значения по умолчанию:

  • appendReleaseDescription (Boolean) — указывает, нужно ли добавить описание доступного выпуска в сообщение уведомления, отображаемое пользователю. По умолчанию — false.
  • descriptionPrefix (String) — указывает строку, с которой необходимо префиксировать описание выпуска при отображении уведомления об обновлении для конечного пользователя. По умолчанию — " Description: ".
  • обязательный атрибутContinueButtonLabel (String): текст, используемый для кнопки, который пользователь должен нажать, чтобы установить обязательное обновление. По умолчанию — "Continue".
  • обязательный атрибутUpdateMessage (String) — текст, используемый в качестве текста уведомления об обновлении, когда обновление указано как обязательное. По умолчанию — "An update is available that must be installed.".
  • optionalIgnoreButtonLabel (String) — текст, используемый для кнопки, который пользователь может нажать, чтобы игнорировать необязательное обновление, доступное. По умолчанию — "Ignore".
  • optionalInstallButtonLabel (String) — текст, используемый для кнопки, который пользователь может нажать, чтобы установить необязательное обновление. По умолчанию — "Install".
  • optionalUpdateMessage (String) — текст, используемый в качестве текста уведомления об обновлении, если обновление является необязательным. По умолчанию — "An update is available. Would you like to install it?". *- updateTitle (String) — текст, используемый в качестве заголовка уведомления об обновлении, отображаемого пользователю. По умолчанию — "Update available".

Пример использования:

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

Метод sync можно вызвать в любом месте, где требуется проверить наличие обновления. Это может быть в deviceready обработчике событий, событии кнопки, click в обратном вызове периодического таймера или в любом другом случае имеет смысл для ваших потребностей. checkForUpdate Как и метод, он запустит сетевой запрос, чтобы проверить наличие обновления в фоновом режиме, поэтому он не повлияет на скорость реагирования потока пользовательского интерфейса или потока JavaScript.

Объекты пакета

getCurrentPackage Методы checkForUpdate вызывают обратные вызовы успешного выполнения, которые при активации предоставляют доступ к объектам пакета. Пакет представляет обновление кода, а также дополнительные метаданные (например, описание, обязательный?). API CodePush имеет различие между следующими типами пакетов:

  1. LocalPackage: представляет скачаемое обновление, которое уже запущено или установлено и ожидает перезапуска приложения.
  2. RemotePackage: представляет доступное обновление на сервере CodePush, который еще не скачан.

LocalPackage

Содержит сведения об обновлении, скачанном локально или уже установленном. Вы можете получить ссылку на экземпляр этого объекта, вызвав codePush.getCurrentPackage метод или как значение, предоставленное для обратного вызова метода успешно.RemotePackage.download

Свойства
  • appVersion: собственная версия приложения, для этого обновления пакета предназначена. (Строка)
  • deploymentKey: ключ развертывания пакета. (Строка)
  • описание обновления. Это то же значение, которое вы указали в CLI при выпуске обновления. (Строка)
  • failedInstall: указывает, было ли установлено это обновление ранее, но откатился. Метод sync автоматически игнорирует обновления, которые ранее завершились сбоем, поэтому при использовании этого свойства необходимо беспокоиться только об этом свойстве checkForUpdate. (Логический)
  • isFirstRun: флаг, указывающий, является ли текущий запуск приложения первым после применения пакета. (Логический)
  • isMandatory: указывает, считается ли обновление обязательным. Это значение, указанное в CLI при выпуске обновления. (Логический)
  • метка: внутренняя метка автоматически присваивается обновлению сервером CodePush, например v5. Это значение однозначно идентифицирует обновление в его развертывании. (Строка)
  • packageHash: хэш-значение SHA обновления. (Строка)
  • packageSize: размер кода, содержащегося в обновлении, в байтах. (Число)
Методы
  • install(installSuccess, installError, installOptions): устанавливает этот пакет в приложение. Поведение установки зависит от предоставленного installOptions. По умолчанию пакет обновления автоматически установлен, и приложение перезагрузится с новым содержимым в следующем запуске приложения. При первом запуске после обновления приложение ожидает codePush.notifyApplicationReady() вызова. После выполнения этого вызова операция установки считается успешной. В противном случае операция установки будет помечена как сбой, и приложение будет возвращено к предыдущей версии при следующем запуске.
InstallOptions

Интерфейс, определяющий несколько вариантов настройки поведения операции установки.

  • installMode: используется для указания InstallMode, используемого для операции установки. По умолчанию — InstallMode.ON_NEXT_RESTART.
  • обязательныйInstallMode: используется для указания InstallMode, используемого для операции установки, если пакет является обязательным. По умолчанию — InstallMode.IMMEDIATE.
  • minimumBackgroundDuration: если установленmodeInstallMode.ON_NEXT_RESUME, используется для указания времени, когда приложение должно находиться в фоновом режиме, прежде чем обновление будет установлено при возобновлении. По умолчанию — 0.

Пример использования:

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

Пример защиты от плохого обновления см. в документации notifyApplicationReady().

RemotePackage

Содержит сведения об обновлении, доступном для скачивания с сервера CodePush. Вы получите ссылку на экземпляр этого объекта, вызвав codePush.checkForUpdate метод, когда обновление доступно. Если вы используете API синхронизации, вам не нужно беспокоиться о RemotePackageнем, так как он будет обрабатывать процесс загрузки и установки автоматически для вас.

Свойства

Наследует RemotePackage все те же свойства, что и те LocalPackageже свойства, но включают один дополнительный:

  • downloadUrl: URL-адрес, в котором доступен пакет для скачивания. Это свойство требуется только для расширенного использования, так как download метод автоматически обрабатывает получение обновлений для вас. (Строка)
Методы
  • abortDownload(abortSuccess, abortError): прерывает текущий сеанс скачивания, если он есть.
  • download(downloadSuccess, downloadError, downloadProgress): скачивает обновление пакета из службы CodePush. Обратный downloadSuccess вызов вызывается с помощью аргумента LocalPackage , представляющего скачанный пакет. Необязательный downloadProgress обратный вызов вызывается несколько раз во время выполнения скачивания с одним DownloadProgress параметром.
DownloadProgres

Определяет формат объекта DownloadProgress, используемый для отправки уведомлений о ходе загрузки обновления периодического обновления.

Свойства
  • totalBytes: размер пакета обновления загрузки в байтах. (Число)
  • receivedBytes: число уже скачанных байтов. (Число)

Пример использования:

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

Перечисления

API CodePush включает следующие объекты перечисления, которые можно использовать для настройки интерфейса обновления и доступны глобально вне window объекта:

InstallMode

Эта перечисление указывается, если требуется, чтобы установленное обновление применялось фактически, и его можно передать в sync методы или LocalPackage.install методы. Он включает следующие значения:

  • ИНТЕРПРЕТАЦИЯ. Обновление будет применено к работающему приложению немедленно. Приложение будет перезагружено с новым содержимым немедленно.
  • ON_NEXT_RESTART. Указывает, что необходимо установить обновление, но не принудительно перезапустить приложение. Когда приложение "естественно" перезапущено (из-за ос или конечного пользователя, убивающего его), обновление будет легко выбрано. Это значение подходит при выполнении автоматических обновлений, так как, скорее всего, это может быть нарушением для конечного пользователя, если приложение внезапно перезагрузилось из нигде, так как они не поняли, что обновление было бы даже загружено. Это режим по умолчанию, используемый как для методов, так sync и LocalPackage.install для методов.

Пример защиты от плохого обновления см. в документации notifyApplicationReady().

RemotePackage

Содержит сведения об обновлении, доступном для скачивания с сервера CodePush. Вы получите ссылку на экземпляр этого объекта, вызвав codePush.checkForUpdate метод, когда обновление доступно. Если вы используете API синхронизации, вам не нужно беспокоиться о RemotePackageнем, так как он будет обрабатывать процесс загрузки и установки автоматически для вас.

Свойства

Наследует RemotePackage все те же свойства, что и те LocalPackageже свойства, но включают один дополнительный:

  • downloadUrl: URL-адрес, в котором доступен пакет для скачивания. Это свойство требуется только для расширенного использования, так как download метод автоматически обрабатывает получение обновлений для вас. (Строка)
Методы
  • abortDownload(abortSuccess, abortError): прерывает текущий сеанс скачивания, если он есть.
  • download(downloadSuccess, downloadError, downloadProgress): скачивает обновление пакета из службы CodePush. Обратный downloadSuccess вызов вызывается с помощью аргумента LocalPackage , представляющего скачанный пакет. Необязательный downloadProgress обратный вызов вызывается несколько раз во время выполнения скачивания с одним DownloadProgress параметром.
DownloadProgres

Определяет формат объекта DownloadProgress, используемый для отправки уведомлений о ходе загрузки обновления периодического обновления.

# Свойства
  • totalBytes: размер пакета обновления загрузки в байтах. (Число)
  • receivedBytes: число уже скачанных байтов. (Число)

Пример использования:

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

Перечисления

API CodePush включает следующие объекты перечисления, которые можно использовать для настройки интерфейса обновления и доступны глобально вне window объекта:

InstallMode

Эта перечисление указывается, если требуется, чтобы установленное обновление применялось фактически, и его можно передать в sync методы или LocalPackage.install методы. Он включает следующие значения:

  • ИНТЕРПРЕТАЦИЯ. Обновление будет применено к работающему приложению немедленно. Приложение будет перезагружено с новым содержимым немедленно.
  • ON_NEXT_RESTART. Указывает, что необходимо установить обновление, но не принудительно перезапустить приложение. Когда приложение "естественно" перезапущено (из-за ос или конечного пользователя, убивающего его), обновление будет легко выбрано. Это значение подходит при выполнении автоматических обновлений, так как, скорее всего, это может быть нарушением для конечного пользователя, если приложение внезапно перезагрузилось из нигде, так как они не поняли, что обновление было бы даже загружено. Это режим по умолчанию, используемый как для методов, так sync и LocalPackage.install для методов.
  • ON_NEXT_RESUME. Указывает, что вы хотите установить обновление, но не хотите перезапустить приложение до следующего возобновления работы пользователя из фонового режима. Таким образом, вы не нарушаете текущий сеанс, но вы можете получить обновление перед ними раньше, чем ждать следующего естественного перезапуска. Это значение подходит для автоматической установки, которая может применяться к возобновлению неинвазивным способом.

SyncStatus

Определяет возможные состояния операции синхронизации. Существует две категории состояний: промежуточный и результат (окончательный). Промежуточные состояния представляют состояния хода выполнения операции синхронизации и не являются окончательными. Состояния результатов представляют окончательные состояния операции синхронизации. Каждая операция синхронизации заканчивается только одним состоянием результата, но может иметь ноль или несколько промежуточных состояний.

  • UP_TO_DATE. Приложение полностью обновлено с настроенным развертыванием.
  • UPDATE_INSTALLED. Доступное обновление установлено и будет выполняться сразу после возврата функции обратного вызова или при следующем возобновлении или перезапуске приложения в зависимости от указанного InstallMode вSyncOptions.
  • UPDATE_IGNORED. Приложение имеет необязательное обновление, которое пользователь решил игнорировать. (Это применимо только при updateDialog использовании)
  • ОШИБКА: произошла ошибка во время sync операции. Это может быть ошибка при взаимодействии с сервером, скачивании или распакачивании обновления. Журналы консоли должны содержать дополнительные сведения о том, что произошло. В этом случае обновление не было применено.
  • IN_PROGRESS: еще одна синхронизация уже запущена, поэтому эта попытка синхронизации была прервана.
  • CHECKING_FOR_UPDATE: сервер CodePush запрашивается для обновления.
  • AWAITING_USER_ACTION: доступно обновление, а для конечного пользователя отображается диалоговое окно подтверждения. (Это применимо только при updateDialog использовании)
  • DOWNLOADING_PACKAGE. Доступное обновление загружается с сервера CodePush.
  • INSTALLING_UPDATE. Доступное обновление было скачано и будет установлено.

Сборка PhoneGap

Этот подключаемый модуль совместим с PhoneGap Build и поддерживает создание android и iOS создает встроенные сборки. Однако для вычисления хэша двоичного содержимого в Android PhoneGap Build необходимо использовать Gradle для создания приложения, которое не является его поведением по умолчанию (используется Ant). Чтобы устранить эту проблему, добавьте следующий элемент в файл config.xml проекта в качестве дочернего <platform name="android"> элемента:

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

Примеры приложений

Сообщество Cordova здорово создало некоторые удивительные открытый код приложения, которые могут служить примерами для разработчиков, которые начинают работу. Ниже приведен список приложений OSS Cordova, которые также используют CodePush, и можно использовать для просмотра того, как другие пользователи используют службу:

Примечание.

Если вы разработали приложение Cordova с помощью CodePush, это открытый исходный код, сообщите нам об этом. Мы хотели бы добавить его в этот список!