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

  • Статья

Важно!

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

Узнайте больше о сроках поддержки и альтернативных вариантах.

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

Примечание

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

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

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

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

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

Примечание

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

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

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

  • Android (cordova-android 4.0.0+) — включая CrossWalk!
  • 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, добавьте https://codepush.appcenter.ms в Content-Security-Policymeta тег в файле 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-cordova, дополнительные сведения см. в release этой команде .

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

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

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

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

Параметры

  • notifySucceededed: необязательный обратный вызов, вызываемый, если подключаемый модуль успешно уведомлен.
  • 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 Описание доступных параметров и их действия см. в справочнике по перечислению.
  • mandatoryInstallMode(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: ".
  • mandatoryContinueButtonLabel(String): текст, используемый для кнопки, который пользователь должен нажать для установки обязательного обновления. По умолчанию — "Continue".
  • mandatoryUpdateMessage(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.

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

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

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

LocalPackage

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

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

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

  • installMode: используется для указания параметра InstallMode , используемого для операции установки. По умолчанию — InstallMode.ON_NEXT_RESTART.
  • mandatoryInstallMode: используется для указания параметра InstallMode , используемого для операции установки, если пакет является обязательным. По умолчанию — InstallMode.IMMEDIATE.
  • minimumBackgroundDuration: если installMode имеет значение InstallMode.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 использования, так как метод автоматически обрабатывает получение обновлений. (String)
Методы
  • abortDownload(abortSuccess, abortError): прерывает текущий сеанс загрузки, если таковой имеется.
  • download(downloadSuccess, downloadError, downloadProgress): скачивает обновление пакета из службы CodePush. Обратный downloadSuccess вызов вызывается с помощью аргумента LocalPackage , представляющего скачанный пакет. Необязательный downloadProgress обратный вызов вызывается несколько раз во время скачивания с одним DownloadProgress параметром.
DownloadProgress

Определяет формат объекта 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 использования, так как метод автоматически обрабатывает получение обновлений. (String)
Методы
  • abortDownload(abortSuccess, abortError): прерывает текущий сеанс загрузки, если таковой имеется.
  • download(downloadSuccess, downloadError, downloadProgress): скачивает обновление пакета из службы CodePush. Обратный downloadSuccess вызов вызывается с помощью аргумента LocalPackage , представляющего скачанный пакет. Необязательный downloadProgress обратный вызов вызывается несколько раз во время скачивания с одним DownloadProgress параметром.
DownloadProgress

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

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

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

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

  • PGDay CodePush Demo — демонстрационное приложение, созданное Rangle.io используется для PhoneGap Day Europe 2016.

Примечание

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