Cordova 客户端 SDK

项目
07/18/2024

重要

Visual Studio App Center 计划于 2025 年 3 月 31 日停用。虽然可以继续使用 Visual Studio App Center，直到它完全停用，但有几种建议的替代方法可以考虑迁移到其中。

此插件为 CodePush 服务提供客户端集成，使你可以轻松地向 Cordova 应用添加动态更新体验。

注意

对 Cordova 应用的支持已于 2022 年 4 月结束。在 App Center 博客中查找详细信息。

工作原理

Cordova 应用由 HTML、CSS 和 JavaScript 文件以及任何随附的图像组成，这些图像由 Cordova CLI 捆绑在一起，并作为特定于平台的二进制文件的一部分分发（即 .ipa 或.apk文件）。发布应用后，更新代码或映像资产需要重新编译并重新分发整个二进制文件。此过程包括要发布到的应用商店的评审时间。

CodePush 插件通过使代码和图像与发布到 CodePush 服务器的更新保持同步，从而在最终用户面前立即获得产品改进。这样，你的应用就会获得脱机移动体验的好处，以及一旦提供旁加载更新的“类似于 Web”的敏捷性。这是一种双赢！

为了确保最终用户始终具有正常运行的应用版本，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

使用入门

注意

本文包含对术语“白名单”的引用，Microsoft 不再使用该术语。在从软件中删除该术语后，我们会将其从本文中删除。

按照常规用途的“入门” 说明设置 CodePush 帐户后，可以从应用的根目录中运行以下命令，启动 CodePush-ifying Cordova 应用：

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

安装 CodePush 插件后，通过以下步骤将应用配置为使用它：

将部署密钥添加到 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>

提醒一下，通过 CLI 创建 CodePush 应用时会为你生成这些密钥。如果需要检索它们，可以运行appcenter codepush deployment list -a <ownerName>/<appName> --displayKeys，并获取要使用的特定部署的密钥（例如StagingProduction）。

重要

我们建议为 iOS 和 Android 创建单独的 CodePush 应用，这就是为什么上述示例为 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>

可以对每个平台使用相同的私钥/公钥对。

如果使用的是 config.xml 文件中的<access origin="*" />元素，则应用已允许与 CodePush 服务器通信，并且可以安全地跳过此步骤。否则，请添加以下附加 <access /> 元素：

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

若要确保应用可以访问符合 CSP 的平台上的 CodePush 服务器，请添加到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 *" />

最后，仔细检查是否已 cordova-plugin-whitelist 安装插件（大多数应用）。若要检查此问题，请运行以下命令：

    cordova plugin ls

如果 cordova-plugin-whitelist 位于列表中，则最好去。否则，请运行以下命令以添加它：

    cordova plugin add cordova-plugin-whitelist

现在可以在应用程序代码中使用插件了。有关示例和 API 文档的详细信息，请参阅示例应用程序。

插件用法

安装并配置 CodePush 插件后，唯一需要向应用添加必要的代码来控制以下策略：

何时（以及检查更新的频率）？（e.g. app开始，以响应单击设置页中的按钮，定期以固定间隔）
当更新可用时，如何将其呈现给最终用户？执行此操作的最简单方法是在应用的 deviceready 事件处理程序中运行以下命令：

codePush.sync();

如果更新可用，它将在下次重启应用时以无提示方式下载，并安装该更新（由最终用户或 OS 显式安装），这可确保最终用户的侵入性最低。如果可用更新是必需的，则会立即安装它，确保最终用户尽快获取它。

如果希望应用更快地发现更新，还可以选择每次应用从后台恢复时调用 sync ，方法是添加以下代码（或等效代码）作为应用的启动行为的一部分。可以根据需要尽可能频繁地进行调用 sync ，因此调用时间与地点取决于个人偏好。

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

此外，如果要显示更新确认对话框（“活动安装”），请在安装可用更新时配置（例如强制立即重启）或以任何方式自定义更新体验，请参阅 sync 该方法的 API 参考，了解如何调整此默认行为。

重要

虽然 Apple 的开发人员协议完全允许对 JavaScript 和资产进行无线更新（这是启用 CodePush 的功能），但它违背了应用显示更新提示的策略。因此，我们建议 App Store 分布式应用在调用sync时不启用updateDialog该选项，而 Google Play 和内部分布式应用（例如 Enterprise、Fabric、HockeyApp）可以选择启用/自定义它。

发布更新

应用配置并分发给用户后，你已进行了一些代码或资产更改，就可以立即发布它们了！执行此操作的最简单（和建议）方法是使用 release-cordova CodePush CLI 中的命令，该命令负责准备和释放对 CodePush 服务器的更新。

注意

在开始发布更新之前，请运行以下命令 appcenter login 登录到 App Center

在最基本的窗体中，此命令只需要一个参数：所有者名称 + “/” + 应用名称。

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

提示

通过使用 App Center CLI set-current 函数，无需使用 -a 标志来指定命令指向的应用。

提示

发布对 CodePush 的更新时，无需在 config.xml 文件中颠簸应用的版本，因为你根本不修改二进制版本。仅当升级 Cordova 或其中一个插件时，才需要颠簸此版本，此时需要向本机存储（s）发布更新。 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 命令以获取更多详细信息。

如果遇到任何问题或有任何问题/评论/反馈，可以通过电子邮件发送我们或在此存储库上打开新问题，我们将回复 ASAP！另请参阅帮助和反馈。

API 参考

CodePush API 通过全局 codePush 对象向应用公开，该对象在事件触发后 deviceready 可用。此 API 公开以下顶级方法：

checkForUpdate：询问 CodePush 服务配置的应用部署是否具有可用的更新。
getCurrentPackage：检索有关当前安装的更新的元数据（例如说明、安装时间、大小）。
getPendingPackage：检索已下载和安装的更新（如果存在）的元数据，但尚未通过重启应用。
notifyApplicationReady：通知 CodePush 运行时已安装的更新被视为成功。如果手动检查并安装更新（即不使用同步方法处理所有更新），则必须调用此方法;否则，CodePush 会将更新视为失败，并在应用下次重启时回滚到以前的版本。
restartApplication：立即重启应用。如果存在挂起的更新，它将立即显示给最终用户。
同步：允许通过单个调用检查更新、下载更新和安装更新。除非需要自定义 UI 或行为，否则我们建议大多数开发人员在将 CodePush 集成到其应用中时使用此方法。

此外，以下对象和枚举也会作为 CodePush API 的一部分全局公开：

InstallMode：定义更新的可用安装模式。
LocalPackage：包含有关本地安装的包的信息。
RemotePackage：包含有关可供下载的更新包的信息。
SyncStatus：定义同步操作的可能中间状态和结果状态。

codePush.checkForUpdate

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

查询 CodePush 服务，查看配置的应用部署是否具有可用的更新。默认情况下，它将使用config.xml文件中配置的部署密钥，但可以通过可选deploymentKey参数指定值来替代该密钥。如果要将用户动态“重定向”到特定部署，例如通过复活日蛋或用户设置开关允许“提前访问”，这非常有用。

更新检查完成后，它将使用两个可能值之一触发 onUpdateCheck 回调：

null 如果没有可用的更新。这种情况发生在以下情况下：
- 配置的部署不包含任何版本，因此无需更新。
- 配置的部署中的最新版本面向的二进制版本不同于当前运行的二进制版本（较旧版本或较新版本）。
- 当前正在运行的应用已具有已配置部署的最新版本，因此它不需要再次发布。
一个 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 回调：

null 如果应用当前正在从二进制文件而不是 CodePush 更新运行 HTML 起始页，这种情况发生在以下情况下：
- 最终用户安装了应用二进制文件，但尚未安装 CodePush 更新
- 最终用户安装了二进制文件的更新（例如存储），该更新清除了旧的 CodePush 更新，并优先返回二进制文件。
一个 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调用syncLocalPackage.install或InstallMode.ON_NEXT_RESUME调用时指定了更新，并且应用尚未重启或恢复（分别）处于此状态。如果要确定是否有挂起的更新，然后提示用户是否要立即重启（通过 codePush.restartApplication）应用更新，则此方法非常有用。

更新检索完成后，它将使用两个可能值之一触发 onSuccess 回调：

null 如果应用当前没有挂起的更新（例如应用已运行最新的可用版本）。
一个 LocalPackage 实例，表示当前挂起的 CodePush 更新的元数据。

参数：

onSuccess：收到有关当前挂起更新的元数据时调用的回调。回调接收上述单个参数。
onError：发生错误时调用的可选回调。回调采用一个错误参数，其中包含错误的详细信息。

示例用法：

codePush.getPendingPackage(function (update) {
    if (update) {
        // An update is currently pending, ask the
        // user if they want to restart
    }
});

codePush.notifyApplicationReady

codePush.notifyApplicationReady(notifySucceeded?, notifyFailed?);

通知 CodePush 运行时，应将全新安装的更新视为成功，因此不需要自动客户端回滚。必须在更新捆绑包的代码中调用此函数。否则，当应用下次重启时，CodePush 运行时将假定已安装的更新失败并回滚到以前的版本。存在此行为以帮助确保最终用户不会被损坏的更新阻止。

如果使用函数 sync ，并在应用启动时执行更新检查，则无需手动调用 notifyApplicationReady ，因为 sync 会为你调用它。之所以存在此行为，是因为假设在应用中调用时 sync 表示成功启动的良好近似值。

参数：

notifySucceeded：如果已成功通知插件，则调用可选回调。
notifyFailed：如果在通知插件时出错，则调用可选回调。

codePush.restartApplication

codePush.restartApplication();

立即重启应用。此方法适用于高级方案，在满足以下条件时主要有用：

应用正在指定安装模式值，或者在ON_NEXT_RESUME调用sync或LocalPackage.install方法时指定安装模式值ON_NEXT_RESTART。在应用重启（由最终用户或 OS）或恢复之前，此操作不会应用更新，因此不会立即向最终用户显示更新。
你有一个特定于应用的用户事件（例如最终用户导航回应用的主页路由），该事件允许你以不显眼的方式应用更新，并且可能会在最终用户面前早于等待，直到下一次重启或恢复为止。

codePush.sync

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

将应用的代码和映像与最新版本同步到配置的部署。 checkForUpdate与检查是否存在更新的方法不同，并允许你控制下一步执行的操作，sync请为你处理更新检查、下载和安装体验。

此方法支持两种不同的（但可自定义）“模式”，以轻松启用具有不同要求的应用：

无提示模式（默认行为），它会自动下载可用更新，并在应用下次重启时应用它们（例如 OS 或最终用户终止它，或设备重启）。这样，整个更新体验对最终用户“无提示”，因为它们看不到任何更新提示或“合成”应用重启。
活动模式（当更新可用时），在下载更新之前提示最终用户获取权限，然后立即应用更新。如果使用强制标志发布更新，最终用户仍会收到有关更新的通知，但他们不会选择忽略更新。

示例用法：

// 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 （数字） - 到目前为止下载的字节数，可用于跟踪下载进度。
syncErrback：在任何同步内部步骤中出错时调用。该方法使用标准 javascript Error 对象作为第一个参数调用。

SyncOptions

sync虽然该方法尝试使用很少的配置轻松执行无提示和主动更新，但它接受“选项”对象，该对象允许自定义上述默认行为的许多方面：

deploymentKey （字符串） - 指定要查询其更新的部署密钥。默认情况下，此值派生自 config.xml 文件，但如果需要对特定调用 sync动态使用其他部署，则可以从脚本端重写该值。
installMode （InstallMode） - 指定何时要安装可选更新（即未标记为必需更新）。默认为 InstallMode.ON_NEXT_RESTART。有关 InstallMode 可用选项的说明及其用途，请参阅枚举参考。
mandatoryInstallMode （InstallMode） - 指定何时安装标记为必需更新的更新。默认为 InstallMode.IMMEDIATE。有关 InstallMode 可用选项的说明及其用途，请参阅枚举参考。
minimumBackgroundDuration （数字） - 指定应用在重新启动应用之前要处于后台的最小秒数。此属性仅适用于使用 InstallMode.ON_NEXT_RESUME安装的更新，并且可用于更快地在最终用户面前获取更新，而不会太模糊。 0默认值为在恢复后立即应用更新，但在后台应用更新的时间长。
ignoreFailedUpdates （Boolean） - 指定如果以前在客户端上安装并回滚可用更新（因为 notifyApplicationReady 未成功调用），是否应忽略可用更新。默认为 true。
updateDialog （UpdateDialogOptions） - 用于确定在更新可用时是否应向最终用户显示确认对话框的“options”对象，如果是，则使用哪些字符串。默认为 null禁用对话框。将此设置为任何 true 值将启用具有默认字符串的对话框，并将对象传递给此参数允许启用对话框，并重写一个或多个默认字符串。

以下列表表示可用选项及其默认值：

appendReleaseDescription （Boolean） - 指示是否要将可用版本的说明追加到显示给最终用户的通知消息。默认为 false。
descriptionPrefix （字符串） - 指示在向最终用户显示更新通知时要为发布说明添加前缀（如果有）的字符串。默认为 " Description: "。
mandatoryContinueButtonLabel （字符串）：要用于最终用户必须按下的按钮的文本才能安装强制更新。默认为 "Continue"。
mandatoryUpdateMessage （字符串） - 当更新指定为必需时，用作更新通知正文的文本。默认为 "An update is available that must be installed."。
optionalIgnoreButtonLabel （字符串） - 最终用户可以按下的按钮使用的文本，以忽略可用的可选更新。默认为 "Ignore"。
optionalInstallButtonLabel （字符串） - 最终用户可按按钮的文本安装可选更新。默认为 "Install"。
optionalUpdateMessage （字符串） - 当更新是可选的时用作更新通知正文的文本。默认为 "An update is available. Would you like to install it?"。 *- updateTitle （字符串） - 用作向最终用户显示的更新通知的标头的文本。默认为 "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与该方法一样，它将运行网络请求来检查后台的更新，因此不会影响 UI 线程或 JavaScript 线程的响应能力。

包对象

和checkForUpdategetCurrentPackage方法调用成功回调（触发时）提供对“包”对象的访问。包表示代码更新以及任何额外的元数据（例如说明，必需？）。 CodePush API 区分以下类型的包：

LocalPackage：表示已下载的更新，该更新已运行或已安装，并且正在等待应用重启。
RemotePackage：表示尚未下载的 CodePush 服务器上的可用更新。

LocalPackage

包含有关本地下载或已安装的更新的详细信息。可以通过调用 codePush.getCurrentPackage 方法或作为提供给方法成功回调的值来获取对此对象的实例的 RemotePackage.download 引用。

属性

appVersion：此包更新适用于应用程序的本机版本。 （字符串）
deploymentKey：包的部署密钥。 （字符串）
说明：更新的说明。这是发布更新时在 CLI 中指定的值。 （字符串）
failedInstall：指示是否已安装此更新，但是否已回滚。此方法 sync 将自动忽略以前失败的更新，因此，如果使用的是 checkForUpdate此属性，则只需担心此属性。 （布尔）
isFirstRun：指示当前应用程序运行是否为应用包后的第一个标志。 （布尔）
isMandatory：指示更新是否被视为必需更新。这是发布更新时在 CLI 中指定的值。 （布尔）
label：CodePush 服务器自动为更新提供的内部标签，例如 v5。此值唯一标识其部署中的更新。 （字符串）
packageHash：更新的 SHA 哈希值。 （字符串）
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 该方法会自动为你处理更新的获取。 （字符串）

方法

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

枚举

CodePush API 包括以下可用于自定义更新体验的“枚举”对象，并且可从对象全局获取 window ：

InstallMode

如果希望实际应用已安装的更新，并且可以传递给 sync 或 LocalPackage.install 方法，则指定此枚举。它包含以下值：

即时：更新将立即应用于正在运行的应用程序。应用程序将立即使用新内容重新加载。
ON_NEXT_RESTART：指示要安装更新，但不强行重启应用。当应用“自然”重启（由于 OS 或最终用户终止应用），更新将无缝提取。执行无提示更新时，此值很合适，因为如果应用突然从无处重启，则可能会对最终用户造成干扰，因为它们甚至不会意识到已下载更新。这是用于和syncLocalPackage.install方法的默认模式。

有关如何防止更新错误的示例，请参阅 notifyApplicationReady（）文档。

RemotePackage

属性

继承 RemotePackage 与该 LocalPackage属性相同的所有属性，但包括一个附加属性：

downloadUrl：包可供下载的 URL。此属性仅用于高级用法，因为 download 该方法会自动为你处理更新的获取。 （字符串）

方法

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

枚举

CodePush API 包括以下可用于自定义更新体验的“枚举”对象，并且可从对象全局获取 window ：

InstallMode

如果希望实际应用已安装的更新，并且可以传递给 sync 或 LocalPackage.install 方法，则指定此枚举。它包含以下值：

即时：更新将立即应用于正在运行的应用程序。应用程序将立即使用新内容重新加载。
ON_NEXT_RESTART：指示要安装更新，但不强行重启应用。当应用“自然”重启（由于 OS 或最终用户终止应用），更新将无缝提取。执行无提示更新时，此值很合适，因为如果应用突然从无处重启，则可能会对最终用户造成干扰，因为它们甚至不会意识到已下载更新。这是用于和syncLocalPackage.install方法的默认模式。
ON_NEXT_RESUME：指示要安装更新，但不希望在下次最终用户从后台恢复应用之前重启应用。这样，就不会中断其当前会话，但可以提前获取更新，而不是等待下一次自然重启。此值适用于可在恢复时以非侵入性方式应用的无提示安装。

SyncStatus

定义同步操作的可能状态。有两类状态：中间和结果（最终）。中间状态表示同步操作的进度状态，并且不是最终状态。结果状态表示同步操作的最终状态。每个同步操作只以一个结果状态结束，但可以有零个或多个中间状态。

UP_TO_DATE：应用已配置部署完全最新。
UPDATE_INSTALLED：已安装可用的更新，将在回调函数返回或应用下次恢复/重启后立即运行，具体取决于 InstallMode 指定的更新 SyncOptions。
UPDATE_IGNORED：应用具有可选的更新，最终用户选择忽略该更新。 （这仅适用于使用时 updateDialog ）
错误：操作期间 sync 发生错误。与服务器通信、下载或解压缩更新时，这可能是一个错误。控制台日志应包含有关所发生情况的详细信息。在这种情况下，未应用任何更新。
IN_PROGRESS：另一个同步已在运行，因此此同步尝试已中止。
CHECKING_FOR_UPDATE：正在查询 CodePush 服务器以获取更新。
AWAITING_USER_ACTION：更新可用，并向最终用户显示确认对话框。 （这仅适用于使用时 updateDialog ）
DOWNLOADING_PACKAGE：正在从 CodePush 服务器下载可用更新。
INSTALLING_UPDATE：已下载可用更新，即将安装。

PhoneGap 生成

此插件与 PhoneGap Build 兼容，支持现装创建 Android 和 iOS 版本。但是，为了使 CodePush 在 Android 上计算二进制内容的哈希，PhoneGap Build 需要使用 Gradle 来生成应用，这不是其默认行为（它使用 Ant）。若要解决此问题，请将以下元素作为元素的<platform name="android">子元素添加到项目的config.xml文件中：

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

示例应用

Cordova 社区亲切地创建了一些令人敬畏的开放源代码应用，这些应用可以作为开发人员入门的示例。以下列表是同时使用 CodePush 的 OSS Cordova 应用，可用于查看其他人如何使用该服务：

PGDay CodePush 演示 - 由用于 PhoneGap Day Europe 2016 的 Rangle.io 创建的演示应用。

注意

如果你已经使用 CodePush 开发了 Cordova 应用，这是开源应用，请告诉我们。我们希望将其添加到此列表中！

通过

Cordova 客户端 SDK

工作原理

支持的 Cordova 平台

使用入门

插件用法

发布更新

API 参考

codePush.checkForUpdate

codePush.getCurrentPackage

codePush.getPendingPackage

codePush.notifyApplicationReady

codePush.restartApplication

codePush.sync

SyncOptions

包对象

LocalPackage

属性

方法

InstallOptions

RemotePackage

属性

方法

DownloadProgress

属性

枚举

InstallMode

RemotePackage

属性

方法

DownloadProgress

# 属性

枚举

InstallMode

SyncStatus

PhoneGap 生成

示例应用

反馈

其他资源