Cordova 客户端 SDK

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

备注

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

它是如何工作的?

Cordova 应用包含 HTML、CSS 和 JavaScript 文件以及任何随附的图像,这些图像与 Cordova CLI 捆绑在一起,并作为特定于平台的二进制文件的一部分分发 (例如,ipa 或 apk 文件) 。 在应用程序发布后,更新代码或图像资产要求您重新编译并重新分发整个二进制文件。 此过程包括要发布到) 存储 (的查看时间。

CodePush 插件通过使你的代码和映像与你发布到 CodePush 服务器的更新保持同步,帮助你立即在最终用户面前获得产品改进。 这样一来,你的应用程序就可以获得脱机移动体验的好处,并可以在其可用时尽快加载更新的 "web 类似" 灵活性。 这是一种双赢!

若要确保最终用户始终具有应用的正常运行版本,CodePush 插件将保留上一次更新的副本,以便在意外推送包含崩溃的更新时,它可以自动回滚。 这样一来,您就可以放心,newfound 发行的灵活性不会导致用户在您有机会在服务器上回滚之前遭到阻止。 这是一种 win-win!

备注

使用本机代码的任何产品更改 (例如升级 Cordova 版本、添加新插件) 无法通过 CodePush 进行分发,因此必须通过) 的适当 (存储进行更新。

支持的 Cordova 平台

完全支持 Cordova 5.0.0 + 以及以下关联平台:

若要检查当前使用的每个 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 插件后,请通过以下步骤将应用配置为使用它:

  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>

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

重要

建议为 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>

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

  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. 若要确保你的应用程序可以访问与 CSP兼容的平台上的 CodePush 服务器,请将添加 https://codepush.appcenter.msContent-Security-Policy meta 文件中的标记 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. 如果 (和) 检查更新的频率如何? (例如,应用启动,以响应在 "设置" 页中按某个固定的时间间隔定期单击某个按钮)
  2. 当更新可用时,如何将其提供给最终用户? 执行此操作的最简单方法是在应用程序的 deviceready 事件处理程序中运行以下内容:
codePush.sync();

如果有可用的更新,则将以无提示方式下载该更新,并在下次重新启动应用程序时安装 () ,这将确保最终用户的侵害性最低的体验。 如果有必需的更新,则会立即安装该更新,从而确保最终用户尽快获得。

如果你希望你的应用程序更快地发现更新,还可以选择在应用 sync 程序的启动行为中添加以下) (代码,以便在应用程序每次从后台恢复时进行调用。 您可以根据 sync 需要频繁地调用,因此在调用它时,它取决于您的个人喜好。

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

此外,如果你想要 ("active install" ) 中显示更新确认对话框,请在安装可用更新时配置 (例如,强制立即重新启动) 或以任何方式自定义更新体验,请参阅该 sync 方法的 API 参考,了解有关如何调整此默认行为的信息。

重要

虽然 Apple 的开发人员协议 完全允许使用 JavaScript 和资产的无线更新 (这就使 CodePush! ) ,它是针对应用程序的策略,用于显示更新提示。 因此,在调用时,建议应用商店分布式应用不启用此 updateDialog 选项 sync ,而 Google Play 和内部分布式应用 (例如 Enterprise、Fabric、HockeyApp) 可以选择启用/自定义它。

发布更新

一旦你的应用程序已配置并分发给你的用户,并且你进行了一些代码或资产更改,就可以立即发布它们! 要执行此操作,最简单的 (和推荐的) 方法是使用 release-cordova CODEPUSH CLI 中的命令,该命令处理准备并发布对 CodePush 服务器的更新。

备注

在开始发布更新之前,请通过运行命令登录 App Center 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

提示

使用 App Center 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 参考

CodePush API 通过全局对象公开给你的应用程序 codePush ,该对象在 deviceready 事件触发后可用。 此 API 公开以下顶级方法:

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

此外,还会在 CodePush API 中全局公开以下对象和枚举:

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 如果应用当前正在从二进制文件而不是 CodePush 更新运行 HTML 起始页,则为。 在下列情况下会发生这种情况:
    • 最终用户已安装应用程序二进制文件,但尚未安装 CodePush 更新
    • 最终用户安装了二进制 (的更新,例如,从应用商店) ,它清除了旧的 CodePush 更新,并优先级回二进制。
  2. 一个 LocalPackage 实例,表示当前正在运行的 CodePush 更新的元数据。

参数:

  • onSuccess:在接收有关当前正在运行更新的元数据时调用的回调。 回调会接收到上述一个参数。
  • onError:在发生错误时调用的可选回调。 回调采用一个错误参数,其中包含错误的详细信息。

示例用法:

codePush.getCurrentPackage(function (update) {
    if (!update) {
        console.log("No updates have been installed");
        return;
    }

    // If the current app "session" represents the first time
    // this update has run, and it had a description provided
    // with it upon release, let's show it to the end user
    if (update.isFirstRun && update.description) {
        // Display a "what's new?" modal
    }
});

codePush. getPendingPackage

codePush.getPendingPackage(onSuccess, onError?);

获取当前挂起的更新 (的元数据(如果存在)) 。 如果已下载并安装了更新,但尚未通过应用重启应用,则会将其视为 "挂起"。 如果在 InstallMode.ON_NEXT_RESTART InstallMode.ON_NEXT_RESUME 调用或时指定了或,则更新只能处于此状态 sync LocalPackage.install ,并且该应用尚未重新启动或恢复 () 。 如果希望确定是否有挂起的更新,然后提示用户要立即重新启动 (通过) 应用该更新,则可以使用此方法 codePush.restartApplication

当更新检索完成时,它将触发 onSuccess 具有以下两个可能值之一的回叫:

  1. null 如果应用当前没有挂起的更新 (例如,应用已在运行最新可用版本) 。
  2. 一个 LocalPackage 实例,表示当前挂起的 CodePush 更新的元数据。

参数:

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

示例用法:

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

codePush. notifyApplicationReady

codePush.notifyApplicationReady(notifySucceeded?, notifyFailed?);

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

如果使用的是 sync 函数,并且在应用启动时进行更新检查,则无需手动调用, notifyApplicationReady 因为 sync 将为你调用它。 存在此行为的原因是, sync 在应用程序中调用时,表示成功启动的良好近似值。

参数:

  • notifySucceeded:如果已成功通知插件,则调用可选回调。
  • notifyFailed:如果通知插件时出现错误,则调用可选回调。

codePush. restartApplication

codePush.restartApplication();

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

  1. ON_NEXT_RESTART ON_NEXT_RESUME 调用 sync 或方法时,应用程序指定的安装模式值为或 LocalPackage.install 。 这不会应用你的更新,直到应用程序重启 (由最终用户或操作系统) 或恢复进行操作,因此不会立即向最终用户显示更新。
  2. 你具有特定于应用程序的用户事件 (例如,最终用户导航回应用程序的主路由) ,它允许你以不引人注目的方式应用更新,并且可能会在最终用户的前面更早地获取更新,而不会等到下一次重新启动或继续。

codePush

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

将你的应用程序的代码和包含最新版本的映像同步到已配置的部署。 与 checkForUpdate 方法不同,后者检查是否存在更新,并使你能够控制接下来要执行的操作,并 sync 处理更新检查、下载和安装体验。

此方法为两个不同的 (提供支持,但可自定义) "模式" 以轻松地启用具有不同要求的应用:

  1. 无提示模式 (默认行为),它会自动下载可用的更新,并在应用程序下次重新启动时应用它们, (例如,OS 或最终用户取消了它,或者设备已重新启动) 。 这样一来,整个更新体验对最终用户是 "无提示" 的,因为他们看不到任何更新提示或 "综合" 应用重启。
  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 });

提示

如果要确定是基于最终用户的设备电池电量级别、网络状况等来检查还是下载可用的更新,请将调用包装在一个条件下,以确保仅在需要时进行调用。

尽管 sync 方法会尽量简化无提示和活动更新的配置,但它也会接受以下可选参数,使你可以自定义上面提到的默认行为的众多方面:

  • syncCallback:当同步过程在整个更新过程中从一个阶段移到另一个阶段时调用。 使用表示当前状态的状态代码调用方法,可以是任何 SyncStatus 值。
  • syncOptions:可选 SyncOptions 参数,用于配置同步操作的行为。
  • downloadProgress:从 CodePush 服务器下载可用的更新时定期调用。 使用对象调用方法 DownloadProgress ,该对象包含以下两个属性:
    • totalBytes (Number) -预期要为此更新接收的总字节数 (也就是说,从以前的版本) 更改的一组文件的大小。
    • 接收 (数字) -到目前为止下载的字节数,可用于跟踪下载进度。
  • syncErrback:在任何同步内部步骤中出现错误时调用。 使用标准 javascript Error 对象作为第一个参数调用方法。

SyncOptions

虽然此 sync 方法会尝试使用少量的配置轻松执行无提示和活动更新,但它会接受 "options" 对象,该对象允许您自定义上述默认行为的众多方面:

  • deploymentKey (字符串) -指定要查询更新的部署密钥。 默认情况下,此值派生自 config.xml 文件,但使用此选项可以在需要为特定调用动态使用不同部署的情况下,从脚本端重写此值 sync
  • installMode (installMode) -指定要安装可选更新(即未标记为强制) 的 (更新)的时间。 默认为 InstallMode.ON_NEXT_RESTARTInstallMode有关可用选项及其功能的说明,请参阅枚举引用。
  • mandatoryInstallMode (InstallMode) -指定要安装标记为强制的更新的时间。 默认为 InstallMode.IMMEDIATEInstallMode有关可用选项及其功能的说明,请参阅枚举引用。
  • minimumBackgroundDuration (号) -指定在重新启动应用之前,应用在后台的最小秒数。 此属性仅适用于使用安装的更新 InstallMode.ON_NEXT_RESUME ,并且可用于更快地在最终用户的顶层获取更新,而不会干扰。 默认值为 0 ,这会在恢复后立即应用更新,但前提是它在后台进行。
  • ignoreFailedUpdates (布尔) -指定是否应在客户 (端上安装并回滚可用的更新,因为未 notifyApplicationReady 成功调用) 。 默认为 true
  • updateDialog (UpdateDialogOptions) -一个 "options" 对象,用于确定在更新可用时是否应向最终用户显示确认对话框,如果有,则使用哪些字符串。 默认值为 null ,这将禁用对话框。 如果将此选项设置为任何 true 值,则会启用具有默认字符串的对话框,并将一个对象传递到此参数,允许启用对话框,并覆盖一个或多个默认字符串。

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

  • appendReleaseDescription (布尔) -指示是否要将可用发布的说明追加到向最终用户显示的通知消息中。 默认为 false
  • descriptionPrefix (string) -指示在向最终用户显示更新通知时要在发布说明前面加上前缀的字符串(如果有)。 默认为 " 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 方法调用成功回调,在触发时,提供对 "package" 对象的访问权限。 此包表示你的代码更新以及任何额外的元数据 (例如 description,必需? ) 。 CodePush API 区分以下类型的包:

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

LocalPackage

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

属性
  • appVersion:此包更新适用于的应用程序的本机版本。 (字符串)
  • deploymentKey:包的部署密钥。 (字符串)
  • 说明:更新说明。 此值与你在发布更新时在 CLI 中指定的值相同。 (字符串)
  • failedInstall:指示此更新是否已安装,但已回滚。 sync方法将自动忽略以前失败的更新,因此,如果使用,你只需考虑此属性 checkForUpdate(布尔)
  • isFirstRun:用于指示当前应用程序是否在应用包后的第一个应用程序运行的标志。 (布尔)
  • isMandatory:指示更新是否被视为必需的。 这是发布更新时在 CLI 中指定的值。 (布尔)
  • 标签: CodePush 服务器自动提供给更新的内部标签,例如 v5 。 此值在其部署中唯一标识更新。 (字符串)
  • packageHash:更新的 SHA 哈希值。 (字符串)
  • packageSize:包含在更新中的代码的大小(以字节为单位)。 (号)
方法
  • 安装 (installSuccess,installError,installOptions):将此包安装到应用程序。 安装行为取决于提供的 installOptions 。 默认情况下,将以无提示方式安装更新包,并在下一个应用程序启动时重新加载应用程序的新内容。 在更新后第一次运行时,应用程序将等待 codePush.notifyApplicationReady() 调用。 进行此调用后,安装操作将被视为成功。 否则,安装操作将被标记为失败,应用程序将在下一次运行时还原为其以前的版本。
InstallOptions

定义多个用于自定义安装操作行为的选项的接口。

  • installMode:用于指定用于安装操作的 installMode 。 默认为 InstallMode.ON_NEXT_RESTART
  • mandatoryInstallMode:如果包是必需的,则用于指定用于安装操作的 InstallMode 。 默认为 InstallMode.IMMEDIATE
  • minimumBackgroundDuration:如果 installModeInstallMode.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):中止当前下载会话(如果有)。
  • 下载 (downloadSuccess,downloadError,downloadProgress):从 CodePush 服务下载包更新。 downloadSuccess使用LocalPackage参数调用回调,该参数表示已下载的包。 在 downloadProgress 下载过程中,通过一个参数多次调用可选回调 DownloadProgress
DownloadProgress

定义 DownloadProgress 对象的格式,该格式用于在更新下载进度上发送期刊更新通知。

属性
  • totalBytes:下载更新包的大小(以字节为单位)。 (号)
  • 接收:已下载的字节数。 (号)

示例用法:

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 包含以下 "enum" 对象,这些对象可用于自定义更新体验,并可在全局范围内提供 window 对象:

InstallMode

当你希望实际应用已安装的更新,并且可以将其传递给或方法时,指定此枚举 sync LocalPackage.install 。 它包括以下值:

  • 立即:会立即将更新应用到正在运行的应用程序。 应用程序将立即重新加载新内容。
  • ON_NEXT_RESTART:指示你要安装该更新,但不强制重新启动该应用。 当应用程序 "自然" 重新启动时 (由于 OS 或最终用户) 终止了该应用程序,将无缝选取该更新。 此值适用于执行无提示更新的情况,因为如果应用程序突然重新启动,最终用户可能会对最终用户造成中断,因为用户甚至无法实现更新。 这是与和方法一起使用的默认 sync 模式 LocalPackage.install

有关如何防范错误更新的示例,请参阅 notifyApplicationReady () 文档

RemotePackage

包含有关可从 CodePush 服务器下载的更新的详细信息。 当更新可用时,通过调用方法来获取对此对象的实例的引用 codePush.checkForUpdate 。 如果你使用的是同步 API,则无需担心 RemotePackage ,因为它会自动为你处理下载和安装过程。

属性

RemotePackage继承所有与相同的属性 LocalPackage ,但包含一个其他属性:

  • downloadUrl:包可用于下载的 URL。 此属性只是高级使用所必需的,因为该 download 方法将自动为你获取更新的获取。 (字符串)
方法
  • abortDownload (abortSuccess,abortError):中止当前下载会话(如果有)。
  • 下载 (downloadSuccess,downloadError,downloadProgress):从 CodePush 服务下载包更新。 downloadSuccess使用LocalPackage参数调用回调,该参数表示已下载的包。 在 downloadProgress 下载过程中,通过一个参数多次调用可选回调 DownloadProgress
DownloadProgress

定义 DownloadProgress 对象的格式,该格式用于在更新下载进度上发送期刊更新通知。

# 属性
  • totalBytes:下载更新包的大小(以字节为单位)。 (号)
  • 接收:已下载的字节数。 (号)

示例用法:

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 包含以下 "enum" 对象,这些对象可用于自定义更新体验,并可在全局范围内提供 window 对象:

InstallMode

当你希望实际应用已安装的更新,并且可以将其传递给或方法时,指定此枚举 sync LocalPackage.install 。 它包括以下值:

  • 立即:会立即将更新应用到正在运行的应用程序。 应用程序将立即重新加载新内容。
  • ON_NEXT_RESTART:指示你要安装该更新,但不强制重新启动该应用。 当应用程序 "自然" 重新启动时 (由于 OS 或最终用户) 终止了该应用程序,将无缝选取该更新。 此值适用于执行无提示更新的情况,因为如果应用程序突然重新启动,最终用户可能会对最终用户造成中断,因为用户甚至无法实现更新。 这是与和方法一起使用的默认 sync 模式 LocalPackage.install
  • ON_NEXT_RESUME:指示你要安装更新,但不希望在最终用户下次从后台恢复应用程序时重新启动应用程序。 这样一来,你就不会中断当前会话,但你可以提前获取更新,而无需等待下一次自然重启。 此值适用于可在恢复时以非侵害性方式应用的无提示安装。

SyncStatus

定义 同步 操作的可能状态。 状态有两个类别:中间和结果 (最终) 。 中间状态表示同步操作的进度状态,而不是最终状态。 结果状态表示同步操作的最终状态。 每个同步操作都以只有一个结果状态结束,但可以有零个或多个中间状态。

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

PhoneGap 生成

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

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

示例应用

Cordova 社区谨慎创建了一些精彩开源应用程序,这些应用程序可用作入门开发人员的示例。 以下列表是也使用 CodePush 的 OSS Cordova 应用,可用于查看其他用户使用该服务的方式:

备注

如果已使用 CodePush 开发了 Cordova 应用,则请告诉我们。 我们想要将其添加到此列表中!