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

Справочник по API ПАКЕТА SDK для собственного клиента React

  • Статья

Внимание

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

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

Подключаемый модуль CodePush состоит из двух компонентов:

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

  2. Собственный API (Objective-C и Java), который позволяет узлу приложения React Native загрузить себя с правильным расположением пакета JS.

В следующих разделах подробно описывается форма и поведение этих API:

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

Если требуетсяreact-native-code-push, объект модуля предоставляет следующие методы верхнего уровня в дополнение к декоратору компонентов корневого уровня:

  • allowRestart: программные перезапуски reallows возникают в результате установки обновления и при необходимости немедленно перезапускает приложение, если ожидающие обновления попытались перезапустить приложение, пока перезапуски были запрещены. Этот метод является расширенным API и необходим только в том случае, если приложение явно запрещает перезапуск через disallowRestart метод.

  • checkForUpdate: запрашивает службу CodePush, доступно ли настроенное развертывание приложения.

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

  • getCurrentPackage: извлекает метаданные о текущем установленном обновлении (например, описание, время установки, размер).

    Примечание.

    v1.10.3-beta По состоянию на модуль CodePush рекомендуется getCurrentPackage использовать getUpdateMetadata*.

  • getUpdateMetadata: извлекает метаданные для установленного обновления (например, описание, обязательно).

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

  • restartApp: немедленно перезапускает приложение. Если ожидается обновление, оно будет немедленно отображаться для конечного пользователя. В противном случае вызов этого метода имеет то же поведение, что и убийство и перезапуск процесса конечным пользователем.

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

codePush

// Wrapper function
codePush(rootComponent: React.Component): React.Component;
codePush(options: CodePushOptions)(rootComponent: React.Component): React.Component;

// Decorator; Requires ES7 support
@codePush
@codePush(options: CodePushOptions)

Используется для упаковки компонента React в компонент React "более высокого порядка", который знает, как синхронизировать пакет JavaScript приложения и ресурсы образа при его подключении. Внутренне компонент более высокого порядка вызывается sync внутри обработчика componentDidMount жизненного цикла, который выполняет проверку обновления, скачивает обновление, если он существует, и устанавливает обновление для вас.

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

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

    // Fully silent update that keeps the app in
// sync with the server, without ever
// interrupting the end user
class MyApp extends Component {}
MyApp = codePush(MyApp);

  2. Автоматическая синхронизация при каждом возобновлении работы приложения. То же самое, что и 1, за исключением того, что мы проверяем наличие обновлений или применяем обновление, если оно существует каждый раз, когда приложение возвращается на передний план после "фона".

    // Sync for updates every time the app resumes.
class MyApp extends Component {}
MyApp = codePush({ checkFrequency: codePush.CheckFrequency.ON_APP_RESUME, installMode: codePush.InstallMode.ON_NEXT_RESUME })(MyApp);

  3. Интерактивный. Когда обновление доступно, предоставьте пользователю запрос на разрешение перед загрузкой, а затем немедленно примените обновление. Если обновление было выпущено с помощью mandatory флага, конечный пользователь по-прежнему будет получать уведомления об обновлении, но он не сможет игнорировать его.

    // Active update that lets the end user know
// about each update, and displays it to them
// immediately after downloading it
class MyApp extends Component {}
MyApp = codePush({ updateDialog: true, installMode: codePush.InstallMode.IMMEDIATE })(MyApp);

  4. Ход выполнения журнала и отображения. Хотя приложение синхронизируется с сервером для обновлений, используйте codePushStatusDidChange перехватчики событий codePushDownloadDidProgress для регистрации различных этапов этого процесса или даже отображения индикатора хода выполнения пользователю.

    // Make use of the event hooks to keep track of
// the different stages of the sync process.
class MyApp extends Component {
    codePushStatusDidChange(status) {
        switch(status) {
            case codePush.SyncStatus.CHECKING_FOR_UPDATE:
                console.log("Checking for updates.");
                break;
            case codePush.SyncStatus.DOWNLOADING_PACKAGE:
                console.log("Downloading package.");
                break;
            case codePush.SyncStatus.INSTALLING_UPDATE:
                console.log("Installing update.");
                break;
            case codePush.SyncStatus.UP_TO_DATE:
                console.log("Up-to-date.");
                break;
            case codePush.SyncStatus.UPDATE_INSTALLED:
                console.log("Update installed.");
                break;
        }
    }

    codePushDownloadDidProgress(progress) {
        console.log(progress.receivedBytes + " of " + progress.totalBytes + " received.");
    }
}
MyApp = codePush(MyApp);

CodePushOptions

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

  • checkFrequency (codePush.CheckFrequency) — указывает, когда требуется проверить наличие обновлений. По умолчанию — codePush.CheckFrequency.ON_APP_START. Ознакомьтесь со ссылкой на перечисление CheckFrequency для описания доступных параметров и того, что они делают.

  • deploymentKey (String) — указывает ключ развертывания, для которого требуется запросить обновление. По умолчанию это значение является производным от файла Info.plist (iOS) и MainActivity.java файла (Android), но этот параметр позволяет переопределить его на стороне скрипта, если необходимо динамически использовать другое развертывание.

  • installMode (codePush.InstallMode) — указывает, когда требуется установить необязательные обновления (те, которые не помечены как обязательные). По умолчанию — codePush.InstallMode.ON_NEXT_RESTART. Ознакомьтесь со ссылкой на перечисление InstallMode для описания доступных параметров и того, что они делают.

  • mandatoryInstallMode (codePush.InstallMode) — указывает, когда требуется установить обновления, которые помечены как обязательные. По умолчанию — codePush.InstallMode.IMMEDIATE. Ознакомьтесь со ссылкой на перечисление InstallMode для описания доступных параметров и того, что они делают.

  • minimumBackgroundDuration (Number) — указывает минимальное количество секунд для приложения, которое должно находиться в фоновом режиме перед перезапуском приложения. Это свойство применяется только к обновлениям, установленным с помощью InstallMode.ON_NEXT_RESUME или InstallMode.ON_NEXT_SUSPENDкоторые могут быть полезны для получения обновления перед конечными пользователями раньше, не будучи слишком навязчивыми. Значение 0по умолчанию, которое применяет обновление сразу после возобновления или если приостановка приложения достаточно долго не имеет значения, однако долго он находится в фоновом режиме.

  • updateDialog (UpdateDialogOptions) — объект options, используемый для определения того, следует ли отображать диалоговое окно подтверждения для конечного пользователя, когда доступно обновление, и если да, какие строки следует использовать. Значение nullпо умолчанию, которое отключает диалоговое окно. При задании этого true значения диалоговое окно будет включать строки по умолчанию и передавать объект этому параметру, что позволяет включить диалоговое окно, а также переопределить одну или несколько строк по умолчанию. Прежде чем включить этот параметр в распределенном приложении App Store, ознакомьтесь с этой заметкой.

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

    • 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?".

    • title (String) — текст, используемый в качестве заголовка уведомления об обновлении, отображаемого конечным пользователем. По умолчанию — "Update available".

  • rollbackRetryOptions (RollbackRetryOptions) — механизм повторных попыток отката позволяет приложению пытаться переустановить обновление, которое ранее откатило (с ограничениями, указанными в параметрах). Это объект "параметры", используемый для определения того, должна ли происходить повторная попытка отката, и если да, какие параметры следует использовать для повторных попыток отката. Это значение по умолчанию имеет значение NULL, которое влияет на отключение механизма повторных попыток. Если задать значение истинности, можно включить механизм повторных попыток с параметрами по умолчанию и передать объект этому параметру, что позволяет включить повторную попытку отката, а также переопределить одно или несколько значений по умолчанию.

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

    • delayInHours (Number) — указывает минимальное время в часах, которое приложение будет ждать после последнего отката, прежде чем пытаться переустановить тот же пакет отката. Не может быть меньше 0. Может быть с плавающей запятой. По умолчанию — 24.

    • maxRetryAttempts (Number) — указывает максимальное количество попыток повторных попыток, которые приложение может сделать до прекращения попытки. Не может быть меньше 1. По умолчанию — 1.

codePushStatusDidChange (перехват событий)

Вызывается при переходе процесса синхронизации с одного этапа на другой в общем процессе обновления. Перехватчик событий вызывается с кодом состояния, который представляет текущее состояние и может быть любым из значений SyncStatus .

codePushDownloadDidProgresss (перехват событий)

Вызывается периодически, когда доступное обновление загружается с сервера CodePush. Метод вызывается с DownloadProgress объектом, который содержит следующие два свойства:

  • totalBytes (Number) — общее количество байтов, которое должно быть получено для этого обновления (это размер набора файлов, измененных с предыдущего выпуска).

  • receivedBytes (Number) — количество скачанных байтов до сих пор, которое можно использовать для отслеживания хода скачивания.

codePush.allowRestart

codePush.allowRestart(): void;

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

Если обновление CodePush в настоящее время ожидается, которое попыталось перезапустить приложение (например, оно использовалось InstallMode.IMMEDIATE), но было заблокировано из-за disallowRestart вызова, вызов allowRestart приведет к немедленному перезапуску. Этот перезапуск позволяет применять обновление как можно скорее, не прерывая работу конечного пользователя во время критических рабочих процессов (например, процесс подключения).

Например, вызов allowRestart активирует немедленный перезапуск, если один из трех сценариев, упомянутых в disallowRestart документации , произошел после disallowRestart вызова. Однако вызов allowRestart не активирует перезагрузку, если следующие моменты имеют значение true:

  1. С момента последнего disallowRestart вызова обновлений CodePush не было установлено, поэтому не требуется перезапускать.

  2. В настоящее время существует ожидающий обновления CodePush, но он был установлен через InstallMode.ON_NEXT_RESTART, поэтому программный перезапуск не требуется.

  3. В настоящее время существует ожидающий обновление CodePush, но оно было установлено через InstallMode.ON_NEXT_RESUME , и приложение еще не было помещено в фоновом режиме, поэтому пока нет необходимости программно перезапустить.

  4. С момента последнего disallowRestart вызова не было сделано никаких звонковrestartApp.

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

Пример использования этого метода см . в разделе disallowRestart .

codePush.checkForUpdate

codePush.checkForUpdate(deploymentKey: String = null, handleBinaryVersionMismatchCallback: (update: RemotePackage) => void): Promise<RemotePackage>;

Запрашивает службу CodePush, чтобы узнать, доступно ли настроенное развертывание приложения. По умолчанию он будет использовать ключ развертывания, настроенный в файле Info.plist (iOS) или MainActivity.java файле (Android), но можно переопределить это, указав значение с помощью необязательного deploymentKey параметра. Это может быть полезно, если вы хотите динамически перенаправить пользователя в определенное развертывание, например разрешить "ранний доступ" через пасхальное яйцо или переключатель параметров пользователя.

Второй необязательный параметр handleBinaryVersionMismatchCallback — это необязательная функция обратного вызова, которую можно использовать для уведомления пользователя о наличии двоичного обновления. Например, рассмотрим вариант использования, в котором в настоящее время установлена двоичная версия 1.0.1 с меткой (меткой push-уведомлений кода) версии 1. Позже машинный код был изменен в цикле разработки, и двоичная версия была обновлена до версии 1.0.2. При активации проверки обновления codepush мы игнорируем обновления с несоответствием двоичной версии (так как обновление не предназначено для двоичной версии установленного приложения). В этом случае установленное приложение (1.0.1) будет игнорировать обновление целевой версии 1.0.2. Вы можете использовать handleBinaryVersionMismatchCallback для предоставления крючка для обработки таких ситуаций.

Внимание

Будьте осторожны, чтобы использовать оповещения в этом обратном вызове, если вы разрабатываете приложение iOS, из-за процесса проверки App Store : приложения не должны заставлять пользователей оценивать приложение, просматривать приложение, скачивать другие приложения или другие аналогичные действия для доступа к функциям, содержимому или использованию приложения.

Этот метод возвращает значение Promise, разрешающее одно из двух возможных значений:

  1. null Если обновление недоступно. Это может произойти в следующих случаях.

    1. Настроенное развертывание не содержит выпусков, поэтому ничего не нужно обновлять.
    2. Последний выпуск в настроенном развертывании предназначен для другой двоичной версии, отличной от используемой в данный момент версии (более старой или более новой).
    3. В настоящее время работающее приложение уже имеет последний выпуск из настроенного развертывания, и поэтому он не нужен снова.
    4. Последний выпуск в настроеном развертывании в настоящее время помечен как отключенный, поэтому его нельзя скачать.
    5. Последний выпуск в настроенном развертывании находится в состоянии "активного развертывания", и запрашивающее устройство не попадает в процент пользователей, имеющих право на это.

  2. RemotePackage Экземпляр, представляющий доступное обновление, которое может быть проверено или более поздней версии.

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

codePush.checkForUpdate()
.then((update) => {
    if (!update) {
        console.log("The app is up to date!");
    } else {
        console.log("An update is available! Should we download it?");
    }
});

codePush.disallowRestart

codePush.disallowRestart(): void;

Временно запрещает программные перезапуски в результате любого из следующих сценариев:

  1. Обновление CodePush устанавливается с помощью InstallMode.IMMEDIATE

  2. Обновление CodePush устанавливается с помощью, InstallMode.ON_NEXT_RESUME и приложение возобновляется из фонового режима (при необходимости регулируется свойством minimumBackgroundDuration ).

  3. Метод restartApp был вызван

    Примечание.

    Шаги 1 и 2 эффективно работают, вызывая restartApp вас, поэтому вы можете подумать, disallowRestart как блокировать любой вызов restartApp, независимо от того, вызывает ли ваше приложение его прямо или косвенно.

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

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

В качестве альтернативы вы также можете использовать InstallMode.ON_NEXT_RESTART каждый раз при вызове sync (который никогда не будет пытаться программно перезапустить приложение), а затем явно вызывать restartApp в точках в приложении, которое "безопасно" для этого. disallowRestart предоставляет альтернативный подход к этому, если код, синхронизированный с сервером CodePush, отделен от кода или компонентов, которые хотят применить политику без перезапуска.

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

class OnboardingProcess extends Component {
    ...

    componentWillMount() {
        // Ensure that any CodePush updates that are
        // synchronized in the background can't trigger
        // a restart while this component is mounted.
        codePush.disallowRestart();
    }

    componentWillUnmount() {
        // Reallow restarts, and optionally trigger
        // a restart if one was currently pending.
        codePush.allowRestart();
    }

    ...
}

codePush.getCurrentPackage

Примечание.

Этот метод считается устаревшим по сравнению с v1.10.3-beta модулем CodePush. Если вы используете эту версию (или более позднюю), рекомендуется использовать codePush.getUpdateMetadata вместо нее, так как она имеет более предсказуемое поведение.

codePush.getCurrentPackage(): Promise<LocalPackage>;

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

Этот метод возвращает значение Promise, разрешающее одно из двух возможных значений:

  1. null Если приложение в настоящее время выполняет пакет JS из двоичного файла, а не обновление CodePush. Это происходит в следующих сценариях:

    1. Конечный пользователь установил двоичный файл приложения и еще не установил обновление CodePush
    2. Конечный пользователь установил обновление двоичного файла (например, из хранилища), которое очищало старые обновления CodePush и дало приоритет двоичному файлу JS в двоичном файле.

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

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

codePush.getCurrentPackage()
.then((update) => {
    // 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.getUpdateMetadata

codePush.getUpdateMetadata(updateState: UpdateState = UpdateState.RUNNING): Promise<LocalPackage>;

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

Этот метод возвращает значение Promise, разрешающее одно из двух возможных значений:

  1. null Если обновление с указанным состоянием в настоящее время не существует. Это происходит в следующих сценариях:

    1. Конечный пользователь еще не установил какие-либо обновления CodePush, и поэтому метаданные недоступны для любых обновлений, независимо от того, что вы указываете в качестве updateState параметра.

    2. Конечный пользователь установил обновление двоичного файла (например, из хранилища), которое очищало старые обновления CodePush и дало приоритет двоичному файлу JS в двоичном файле. Это будет демонстрировать то же поведение, что и #1

    3. Для updateState параметра задано UpdateState.RUNNINGзначение, но в настоящее время приложение не выполняет обновление CodePush. Возможно, ожидается обновление, но приложение еще не было перезапущено, чтобы сделать его активным.

    4. Параметр updateState имеет значение UpdateState.PENDING, но приложение не имеет каких-либо ожидающих обновлений.

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

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

// Check if there's currently a CodePush update running, and if
// so, register it with the HockeyApp SDK (https://github.com/slowpath/react-native-hockeyapp)
// so that crash reports will correctly display the JS bundle version the user was running.
codePush.getUpdateMetadata().then((update) => {
    if (update) {
        hockeyApp.addMetadata({ CodePushRelease: update.label });
    }
});

// Check to see if there's still an update pending.
codePush.getUpdateMetadata(UpdateState.PENDING).then((update) => {
    if (update) {
        // There's a pending update, do we want to force a restart?
    }
});

codePush.notifyAppReady

codePush.notifyAppReady(): Promise<void>;

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

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

Примечание.

Этот метод также называется псевдонимом notifyApplicationReady (для обратной совместимости).

codePush.restartApp

codePush.restartApp(onlyIfUpdateIsPending: Boolean = false): void;

Немедленно перезапускает приложение. Если параметру предоставлено onlyIfUpdateIsPending значение истины, приложение будет перезапущено только в том случае, если ожидается применение ожидающего обновления.

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

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

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

codePush.sync

codePush.sync(options: Object, syncStatusChangeCallback: function(syncStatus: Number), downloadProgressCallback: function(progress: DownloadProgress), handleBinaryVersionMismatchCallback: function(update: RemotePackage)): Promise<Number>;

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

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

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

  2. Активный режим, который, когда обновление доступно, запрашивает пользователю разрешение перед загрузкой, а затем немедленно применяет обновление. Если обновление было выпущено с помощью mandatory флага, конечный пользователь по-прежнему будет получать уведомления об обновлении, но он не сможет игнорировать его.

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

// Fully silent update that keeps the app in
// sync with the server, without ever
// interrupting the end user
codePush.sync();

// Active update, which lets the end user know
// about each update, and displays it to them
// immediately after downloading it
codePush.sync({ updateDialog: true, installMode: codePush.InstallMode.IMMEDIATE });

Совет

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

SyncOptions

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

  • deploymentKey (String) — ссылка на CodePushOptions.

  • installMode (codePush.InstallMode) — ссылка на CodePushOptions.

  • обязательный кодInstallMode (codePush.InstallMode) — см. ссылкуCodePushOptions.

  • minimumBackgroundDuration (Number) — ссылка CodePushOptions.

  • updateDialog (UpdateDialogOptions) — ссылка на CodePushOptions.

  • rollbackRetryOptions (RollbackRetryOptions) — см. ссылкуCodePushOptions.

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

// Use a different deployment key for this
// specific call, instead of the one configured
// in the Info.plist file
codePush.sync({ deploymentKey: "KEY" });

// 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({ installMode: codePush.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({ mandatoryInstallMode: codePush.InstallMode.ON_NEXT_RESUME });

// Changing the title displayed in the
// confirmation dialog of an "active" update
codePush.sync({ updateDialog: { title: "An update is available!" } });

// Displaying an update prompt which includes the
// description for the CodePush release
codePush.sync({
   updateDialog: {
    appendReleaseDescription: true,
    descriptionPrefix: "\n\nChange log:\n"
   },
   installMode: codePush.InstallMode.IMMEDIATE
});

// Shortening the retry delay and increasing
// the number of maximum retry attempts
// in comparison to defaults
codePush.sync({
   rollbackRetryOptions: {
    delayInHours: 8,
    maxRetryAttempts: 3
   }
});

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

  • syncStatusChangedCallback ((syncStatus: Number) => void) — вызывается при переходе процесса синхронизации с одного этапа на другой в общем процессе обновления. Метод вызывается с кодом состояния, который представляет текущее состояние и может быть любым из значений SyncStatus .

  • downloadProgressCallback ((progress: DownloadProgress) => void) — вызывается периодически, когда доступное обновление загружается с сервера CodePush. Метод вызывается с DownloadProgress объектом, который содержит следующие два свойства:

    • totalBytes (Number) — общее количество байтов, которое должно быть получено для этого обновления (это размер набора файлов, измененных с предыдущего выпуска).

    • receivedBytes (Number) — количество скачанных байтов до сих пор, которое можно использовать для отслеживания хода скачивания.

  • handleBinaryVersionMismatchCallback ((update: RemotePackage) => void) — вызывается при наличии любого двоичного обновления. Метод вызывается с RemotePackage объектом. Дополнительные сведения см. в разделе codePush.checkForUpdate .

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

// Prompt the user when an update is available
// and then display a "downloading" modal
codePush.sync({ updateDialog: true },
  (status) => {
      switch (status) {
          case codePush.SyncStatus.DOWNLOADING_PACKAGE:
              // Show "downloading" modal
              break;
          case codePush.SyncStatus.INSTALLING_UPDATE:
              // Hide "downloading" modal
              break;
      }
  },
  ({ receivedBytes, totalBytes, }) => {
    /* Update download modal progress */
  }
);

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

  • codePush.SyncStatus.UP_TO_DATE (4) — приложение обновлено с сервером CodePush.

  • codePush.SyncStatus.UPDATE_IGNORED (5) — приложение имело необязательное обновление, которое пользователь решил игнорировать. (Это применимо только при updateDialog использовании)

  • codePush.SyncStatus.UPDATE_INSTALLED (6) — обновление установлено и будет выполняться сразу после syncStatusChangedCallback возврата функции или при следующем возобновлении или перезапуске приложения в зависимости от указанного InstallMode вSyncOptions.

  • codePush.SyncStatus.SYNC_IN_PROGRESS (7) — выполняется текущая sync операция, которая предотвращает выполнение текущего вызова.

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

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

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

  • LocalPackage: представляет скачаемое обновление, которое уже запущено или установлено и ожидает перезапуска приложения.

  • RemotePackage: представляет доступное обновление на сервере CodePush, который еще не скачан.

LocalPackage

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

Свойства
  • appVersion: двоичная версия приложения, от которую зависит это обновление. Это значение, указанное с помощью appStoreVersion параметра при вызове команды CLI release . (Строка)
  • deploymentKey: ключ развертывания, который использовался для первоначальной загрузки этого обновления. (Строка)
  • описание обновления. Это то же значение, которое вы указали в CLI при выпуске обновления. (Строка)
  • failedInstall: указывает, было ли установлено это обновление ранее, но откатился. Метод sync автоматически игнорирует обновления, которые ранее завершились ошибкой, поэтому при использовании этого свойства необходимо беспокоиться только об этом свойстве checkForUpdate. (Логический)
  • isFirstRun: указывает, является ли обновление первым запуском обновления после установки. Это полезно для определения того, хотите ли вы показать "Что нового?" Пользовательский интерфейс для конечного пользователя после установки обновления. (Логический)
  • isMandatory: указывает, считается ли обновление обязательным. Это значение, указанное в CLI при выпуске обновления. (Логический)
  • isPending: указывает, находится ли это обновление в состоянии ожидания. Когда trueэто означает, что обновление было скачано и установлено, но приложение перезагрузило его, необходимое для его применения еще не произошло, и именно поэтому его изменения в настоящее время не отображаются для конечного пользователя. (Логический)
  • метка: внутренняя метка автоматически присваивается обновлению сервером CodePush, например v5. Это значение однозначно идентифицирует обновление в его развертывании. (Строка)
  • packageHash: хэш-значение SHA обновления. (Строка)
  • packageSize: размер кода, содержащегося в обновлении, в байтах. (Число)
Методы
  • install(installMode: codePush.InstallMode = codePush.InstallMode.ON_NEXT_RESTART, minimumBackgroundDuration = 0): Promise<void>: устанавливает обновление, сохраняя его на диске, где среда выполнения ожидает найти последнюю версию приложения. Параметр installMode управляет, когда изменения отображаются пользователю. Значением по умолчанию является ожидание следующего перезапуска приложения, чтобы отобразить изменения, но можно обратиться к InstallMode ссылке перечисления для описания доступных параметров и того, что они делают. installMode Если для параметра задано InstallMode.ON_NEXT_RESUMEзначение, minimumBackgroundDuration параметр позволяет контролировать время, когда приложение должно находиться в фоновом режиме, прежде чем принудительно установить после возобновления.

RemotePackage

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

Свойства

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

  • downloadUrl: URL-адрес, в котором доступен пакет для скачивания. Это свойство требуется только для расширенного использования, так как download метод автоматически обрабатывает получение обновлений для вас. (Строка)
Методы
  • download(downloadProgressCallback?: Function): Promise<LocalPackage>: Скачивает доступное обновление из службы CodePush. downloadProgressCallback Если задано, он будет вызываться периодически с DownloadProgress объектом ({ totalBytes: Number, receivedBytes: Number }), который сообщает о ходе скачивания, пока не завершится. Возвращает обещание, которое разрешается с LocalPackageпомощью .

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

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

InstallMode

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

  • codePush.InstallMode.ИНТЕРПРЕТАЦИЯ (0) — указывает, что необходимо немедленно установить обновление и перезапустить приложение. Это значение подходит для сценариев отладки, а также при отображении запроса на обновление для пользователя, так как они ожидают, что изменения будут отображаться сразу после принятия установки. Кроме того, этот режим можно использовать для принудительного применения обязательных обновлений, так как он удаляет потенциально нежелательные задержки между установкой обновления и при следующем перезапуске или возобновлении приложения.

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

  • codePush.InstallMode.ON_NEXT_RESUME (2) — указывает, что вы хотите установить обновление, но не хотите перезапускать приложение до следующего момента, когда конечный пользователь возобновляет его из фонового режима. Таким образом, вы не нарушаете текущий сеанс, но вы можете получить обновление перед ними раньше, чем ждать следующего естественного перезапуска. Это значение подходит для автоматической установки, которая может применяться к возобновлению неинвазивным способом.

  • codePush.InstallMode.ON_NEXT_SUSPEND (3) — указывает, что вы хотите установить обновление, пока оно находится в фоновом режиме, но только после того, как оно находится в minimumBackgroundDuration фоновом режиме в течение секунд (0 по умолчанию), чтобы контекст пользователя не потерялся, если приостановка приложения не достаточно долго не имеет значения.

CheckFrequency

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

  • codePush.CheckFrequency.ON_APP_START (0) — указывает, что вы хотите проверить наличие обновлений при запуске процесса приложения.

  • codePush.CheckFrequency.ON_APP_RESUME (1) — указывает, что вы хотите проверить наличие обновлений при каждом возврате приложения на передний план после того, как пользователь нажимал кнопку "Главная", приложение запускает отдельный процесс оплаты и т. д.

  • codePush.CheckFrequency.MANUAL (2) — отключите автоматическую проверку обновлений, но проверяется только при codePush.sync() вызове в коде приложения.

SyncStatus

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

  • codePush.SyncStatus.CHECKING_FOR_UPDATE (0) — сервер CodePush запрашивается для обновления.
  • codePush.SyncStatus.AWAITING_USER_ACTION (1) — доступно обновление, а для конечного пользователя отображается диалоговое окно подтверждения. (Это применимо только при updateDialog использовании)
  • codePush.SyncStatus.DOWNLOADING_PACKAGE (2) — доступное обновление загружается с сервера CodePush.
  • codePush.SyncStatus.INSTALLING_UPDATE (3) — доступное обновление было скачано и будет установлено.
  • codePush.SyncStatus.UP_TO_DATE (4) — приложение полностью обновлено с настроенным развертыванием.
  • codePush.SyncStatus.UPDATE_IGNORED (5) — приложение имеет необязательное обновление, которое пользователь решил игнорировать. (Это применимо только при updateDialog использовании)
  • codePush.SyncStatus.UPDATE_INSTALLED (6) — доступное обновление установлено и будет выполняться сразу после syncStatusChangedCallback возврата функции или при следующем возобновлении или перезапуске приложения в зависимости от указанного InstallMode в SyncOptions.
  • codePush.SyncStatus.SYNC_IN_PROGRESS (7) — выполняется непрерывная sync операция, препятствующая выполнению текущего вызова.
  • codePush.SyncStatus.UNKNOWN_ERROR (-1) — операция синхронизации обнаружила неизвестная ошибка.

UpdateState

В этой перечислении указывается состояние, в котором в данный момент выполняется обновление, и его можно указать при вызове getUpdateMetadata метода. Он включает следующие значения:

  • codePush.UpdateState.RUNNING (0) — указывает, что обновление представляет версию приложения, работающего в настоящее время. Это может быть полезно для идентификации атрибутов приложения, таких как отображение описания выпуска в диалоговом окне "Что нового?" или отправки последней версии в службу аналитики или аварийного создания отчетов.

  • codePush.UpdateState.PENDING (1) — указывает, что обновление установлено, но приложение еще не было перезапущено. Это может быть полезно для определения того, существует ли ожидающее обновление, которое может потребоваться принудительно выполнить программный перезапуск (через restartApp) для применения.

  • codePush.UpdateState.LATEST (2) — указывает, что обновление представляет последний доступный выпуск и может быть запущенным или ожидающим.

Справочник по API Objective-C (iOS)

API Objective-C доступен путем импорта заголовка CodePush.h в файл AppDelegate.m и состоит из одного общедоступного класса с именем CodePush.

CodePush

Содержит статические методы для извлеченияNSURL, представляющего последний файл пакета JavaScript, и его можно передать initWithBundleURL RCTRootViewметоду при загрузке приложения в файле AppDelegate.m.

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

  1. Когда конечный пользователь устанавливает приложение из магазина (например 1.0.0), он получит пакет JS, содержащийся в двоичном файле. Это поведение, которое вы получаете без использования CodePush, но мы убедимся, что он не нарушает :)

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

  3. Как только вы выпустили обновление в магазине приложений (например 1.1.0), а конечные пользователи обновят его, они снова получат пакет JS, содержащийся в двоичном файле. Это поведение гарантирует, что обновления CodePush, предназначенные для предыдущей двоичной версии, не используются (так как мы не знаем, что они будут работать), а конечные пользователи всегда имеют рабочую версию вашего приложения.

  4. Повторите #2 и #3 в качестве выпусков CodePush и выпусков магазина приложений продолжаются в бесконечность (и за ее пределами?)

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

Методы

  • (NSURL *)bundleURL — возвращает последний пакет NSURL JS, как описано выше. Этот метод предполагает, что имя пакета JS, содержащегося main.jsbundleв двоичном файле приложения.

  • (NSURL *)bundleURLForResource:(NSString *)resourceName — эквивалент bundleURL метода, но также позволяет настраивать имя пакета JS, который выполняет поиск в двоичном файле приложения. Это полезно, если вы не именуете этот файл main (это соглашение по умолчанию). Этот метод предполагает, что расширение пакета JS является *.jsbundle.

  • (NSURL *)bundleURLForResource:(NSString *)resourceName withExtension:(NSString *)resourceExtension: Эквивалент bundleURLForResource: метода, но также позволяет настраивать расширение, используемое пакетом JS, который выполняет поиск в двоичном файле приложения. Это полезно, если вы не именуете этот файл *.jsbundle (это соглашение по умолчанию).

  • (void)overrideAppVersion:(NSString *)appVersionOverride — задает версию двоичного интерфейса приложения, которая по умолчанию использует версию App Store, указанную в CFBundleShortVersionString info.plist. Это должно вызываться один раз перед загрузкой URL-адреса пакета.

  • (void)setDeploymentKey:(NSString *)deploymentKey — задает ключ развертывания, который приложение должно использовать при запросе обновлений. Это динамическая альтернатива настройке ключа развертывания в info.plist или указанию ключа развертывания в JS при вызове checkForUpdate илиsync.

Справочник по API Java (Android)

API для React Native 0.60 версии и выше

Так как autolinking используется react-native.config.js для связывания подключаемых модулей, конструкторы указываются в этом файле. Но можно переопределить пользовательские переменные для управления подключаемым модулем CodePush, поместив эти значения в строковые ресурсы.

  • Открытый ключ — используемый для проверки пакета в компоненте подписывания кода. Дополнительные сведения о функции подписывания кода см. в разделе "Подписывание кода". Чтобы задать открытый ключ, необходимо добавить содержимое открытого ключа strings.xml в имя CodePushPublicKey. CodePush автоматически получает это свойство и включает функцию подписывания кода. Например:

    <string moduleConfig="true" name="CodePushPublicKey">your-public-key</string>

  • URL-адрес сервера, используемый для указания URL-адреса сервера CodePush. Значение по умолчанию: "https://codepush.appcenter.ms/" переопределяется путем добавления пути к strings.xml имени CodePushServerUrl. CodePush автоматически получает это свойство и будет использовать этот путь для отправки запросов. Например:

    <string moduleConfig="true" name="CodePushServerUrl">https://yourcodepush.server.com</string>

API для React Native ниже 0,60

API Java предоставляется путем импорта com.microsoft.codepush.react.CodePush класса в файл MainActivity.java и состоит из одного общедоступного класса с именем CodePush.

CodePush

Создает среду выполнения клиента CodePush и представляет ReactPackage экземпляр, добавляемый в список пакетов приложения.

Конструкторы

  • CodePush(String deploymentKey, Activity mainActivity) — создает новый экземпляр среды выполнения CodePush, который будет использоваться для запроса службы обновлений с помощью предоставленного ключа развертывания. Параметр mainActivity всегда должен быть задан this при настройке списка пакетов React внутри MainActivity класса. Этот конструктор помещает среду выполнения CodePush в "режим выпуска", поэтому если вы хотите включить поведение отладки, используйте следующий конструктор.

  • CodePush(String deploymentKey, Activity mainActivity, bool isDebugMode) — эквивалентен предыдущему конструктору, но позволяет указать, должна ли среда выполнения CodePush находиться в режиме отладки или нет. При использовании этого конструктора isDebugMode параметр всегда BuildConfig.DEBUG должен оставаться синхронизированным с типом сборки. При включении CodePush в режим отладки включены следующие действия:

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

    2. Локальный кэш, который среда выполнения React Native поддерживает в режиме отладки, удаляется при установке обновления CodePush. Это гарантирует, что при перезапуске приложения после применения обновления можно увидеть ожидаемые изменения. Как только этот PR-запрос объединен, нам больше не придется делать это.

  • CodePush(String deploymentKey, Context context, boolean isDebugMode, Integer publicKeyResourceDescriptor) — эквивалентен предыдущему конструктору, но позволяет указать дескриптор ресурса открытого ключа, необходимый для чтения содержимого открытого ключа. Дополнительные сведения о функции подписывания кода см. в разделе "Подписывание кода".

  • CodePush(String deploymentKey, Context context, boolean isDebugMode, String serverUrl) — конструктор позволяет указать URL-адрес сервера CodePush. Значение "https://codepush.appcenter.ms/" по умолчанию: переопределяется по значению, указанному в serverUrl.

Статические методы

  • getBundleUrl() — возвращает путь к последней версии файла пакета JS приложения, предполагая, что это имя index.android.bundleресурса. Если приложение использует другое имя пакета, используйте перегруженную версию этого метода, которая позволяет указать его. Этот метод имеет то же поведение разрешения, что и эквивалент Objective-C, описанный выше.

  • getBundleUrl(String bundleName) — возвращает путь к последней версии файла пакета JS приложения, используя указанное имя ресурса (например index.android.bundle). Этот метод имеет то же поведение разрешения, что и эквивалент Objective-C, описанный выше.

  • overrideAppVersion(String appVersionOverride) — задает версию двоичного интерфейса приложения, которая по умолчанию используется для версии Play Store, указанной в versionName файле build.gradle. Это должно вызываться один раз перед созданием экземпляра CodePush.