NativeScript 的 CodePush 插件

为您的 NativeScript 应用程序提供实时更新服务！

📣 更新 2019 年 5 月 27 日：在官方发布之前，我们很可能会更改此解决方案的名称。请耐心等待！

可选阅读：这是什么，以及它是如何工作的

NativeScript 应用程序由 XML/HTML、CSS 和 JavaScript 文件以及任何相关图像组成，这些文件由 NativeScript CLI 打包并作为平台特定二进制文件（即 .ipa 或 .apk 文件）的一部分进行分发。一旦应用程序发布，更新代码（例如修复错误、添加新功能）或图像资源，则需要您重新编译和重新分发整个二进制文件，这当然包括您发布到商店时关联的任何审查时间。

CodePush 插件通过保持您的代码和图像与您发布到 CodePush 服务器的更新同步，帮助您立即将产品改进呈现在最终用户面前。这样，您的应用程序获得离线移动体验的优点，以及更新一有可用就侧载的“网络”敏捷性。这是一个双赢！

为了确保您的最终用户始终拥有您应用程序的功能版本，CodePush 插件会保留前一个更新的副本，以便在您意外发布包含崩溃的更新时，可以自动回滚。这样，您可以放心地休息，您的新发布敏捷性不会导致用户在您有机会在服务器上回滚之前被阻止。这是一个赢三次的局面！

解决方案的架构概述 - 您无需担心这一切

什么可以（并将）CodePush

• 您的 /app 文件夹内的任何内容。
• 您的 /node_modules 文件夹内的任何内容。

💁‍♂️ 注意，我们实际上并没有使用这些文件夹，但在 platforms/ios/<appname>/app 和 platforms/android/app/src/main/assets/app 中的 app 文件夹中，其好处是我们“不关心”您是否使用 Webpack、Uglify 或您用于压缩或混淆应用程序资源的任何其他工具。

什么不能（将不会）CodePush

• NativeScript 平台更新。例如：将 tns-android 从版本 2.5.1 更新到 2.5.2。
• 需要依赖不同版本的本机库的插件更新。

因此，只要您在 package.json 中不更改依赖项和 tns 平台的版本，您就可以无忧地推送。如果您确实更改了依赖项的版本，请确保没有更改平台库。

入门

全局安装 NativeScript CodePush CLI

npm i -g nativescript-code-push-cli

💁‍♂️ 这将也将全局 nativescript-code-push 命令添加到您的计算机上。您可以使用 nativescript-code-push -v 检查当前安装的版本。

登录或注册服务

检查您是否已登录，以及使用哪个电子邮件地址

nativescript-code-push whoami

如果您已有账户，请登录

nativescript-code-push login

如果您还没有账户，请注册

nativescript-code-push register

这将在浏览器中打开，您可以提供您的凭据，之后您可以创建一个访问密钥，并将其粘贴到控制台。

现在你应该在你的家目录中有一个.nativescript-code-push.config文件，它将自动使你从这个机器上与服务器进行认证。

请注意，你可以使用该Web界面来管理你的应用，但CLI（命令行界面）功能更强大，因此建议使用命令行界面。

要注销，你可以运行nativescript-code-push logout，这将删除配置文件。

要执行无头登录（不打开浏览器），你可以这样做：nativescript-code-push login --accessKey <access key>。

将你的应用与服务注册

为你要针对的每个平台创建一个应用。这样，你可以为iOS和Android分别推出更新。

⚠️ appname必须唯一，且不应包含连字符（-）。

nativescript-code-push app add <appname> <platform>

# examples:
nativescript-code-push app add MyAppIOS ios
nativescript-code-push app add MyAppAndroid android

💁‍♂️ 这将显示你连接到CodePush服务器所需的部署密钥。如果你想在任何时候列出这些密钥，请使用nativescript-code-push deployment ls <appName> --displayKeys。

💁‍♂️ 所有新应用都自动附带两个部署（Staging和Production），这样你就可以开始向多个渠道分发更新。如果你需要更多渠道/部署，只需运行：nativescript-code-push deployment add <appName> <deploymentName>。

💁‍♂️ 想要重命名你的应用吗？任何时候，使用以下命令：nativescript-code-push app rename <oldName> <newName>

💁‍♂️ 想要删除应用吗？任何时候，使用以下命令：nativescript-code-push app remove <appName> - 这意味着任何配置为使用它的应用将显然停止接收更新。

列出你的已注册应用

nativescript-code-push app ls

将此插件添加到你的应用

tns plugin add nativescript-code-push

⚠️ 如果你在你的应用中限制了互联网访问，请确保将我们的CodePush服务器（https://nativescript-codepush-server.herokuapp.com）和文件服务器（https://s3.eu-west-1.amazonaws.com）列入白名单。

检查更新

在安装并配置了CodePush插件之后，剩下的事情就是将必要的代码添加到你的应用中，以控制何时检查更新。

如果有更新可用，它将静默下载并安装。

然后根据提供的InstallMode，插件将等待下一次冷启动（InstallMode.ON_NEXT_RESTART）、热重启（InstallMode.ON_NEXT_RESUME）或对用户提示的肯定响应（InstallMode.IMMEDIATE）。

请注意，苹果不希望你提示用户重新启动你的应用，所以仅在iOS上为Enterprise分发的应用（或通过TestFlight等测试你的应用时）使用InstallMode.IMMEDIATE。

💁‍♂️ 查看我们的示例以获取一个可靠的示例。

// import the main plugin classes
import { CodePush } from "nativescript-code-push";

// and at some point in your app:
CodePush.sync({
  deploymentKey: "your-deployment-key" // note that this key depends on the platform you're running on (see the example below)
});

有一些你可以配置的东西 - 这个TypeScript示例具有所有可能选项

import { CodePush, InstallMode, SyncStatus } from "nativescript-code-push";
import { isIOS } from "tns-core-modules/platform";

CodePush.sync({
    deploymentKey: isIOS ? "your-ios-deployment-key" : "your-android-deployment-key",
    installMode: InstallMode.ON_NEXT_RESTART, // this is the default install mode; the app updates upon the next cold boot (unless the --mandatory flag was specified while pushing the update) 
    mandatoryInstallMode: isIOS ? InstallMode.ON_NEXT_RESUME : InstallMode.IMMEDIATE, // the default is InstallMode.ON_NEXT_RESUME which doesn't bother the user as long as the app is in the foreground. InstallMode.IMMEDIATE shows an installation prompt. Don't use that for iOS AppStore distributions because Apple doesn't want you to, but if you have an Enterprise-distributed app, go right ahead!
    updateDialog: { // only used for InstallMode.IMMEDIATE
      updateTitle: "Please restart the app", // an optional title shown in the update dialog 
      optionalUpdateMessage: "Optional update msg",   // a message shown for non-"--mandatory" releases 
      mandatoryUpdateMessage: "Mandatory update msg", // a message shown for "--mandatory" releases
      optionalIgnoreButtonLabel: "Later", // if a user wants to continue their session, the update will be installed on next resume
      mandatoryContinueButtonLabel: isIOS ? "Exit now" : "Restart now", // On Android we can kill and restart the app, but on iOS that's not possible so the user has to manually restart it. That's why we provide a different label in this example.
      appendReleaseDescription: true // appends the description you (optionally) provided when releasing a new version to CodePush
    }
  }, (syncStatus: SyncStatus): void => {
    console.log("CodePush syncStatus: " + syncStatus);
    if (syncStatus === SyncStatus.UP_TO_DATE) {
      console.log("CodePush: no pending updates; you're running the latest version!");
    } else if (syncStatus === SyncStatus.UPDATE_INSTALLED) {
      console.log("CodePush: update installed - it will be activated upon next cold boot");
    }
});

var CodePush = require("nativescript-code-push").CodePush;
var InstallMode = require("nativescript-code-push").InstallMode;
var SyncStatus = require("nativescript-code-push").SyncStatus;
var platform = require("tns-core-modules/platform");

CodePush.sync({
    deploymentKey: platform.isIOS ? "your-ios-deployment-key" : "your-android-deployment-key",
    installMode: InstallMode.ON_NEXT_RESTART,
    mandatoryInstallMode: platform.isIOS ? InstallMode.ON_NEXT_RESUME : InstallMode.IMMEDIATE,
    updateDialog: {
      optionalUpdateMessage: "Optional update msg",
      updateTitle: "Please restart the app",
      mandatoryUpdateMessage: "Mandatory update msg",
      optionalIgnoreButtonLabel: "Later",
      mandatoryContinueButtonLabel: platform.isIOS ? "Exit now" : "Restart now",
      appendReleaseDescription: true // appends the description you (optionally) provided when releasing a new version to CodePush
    }
}, function (syncStatus) {
    if (syncStatus === SyncStatus.UP_TO_DATE) {
      console.log("CodePush: no pending updates; you're running the latest version!");
    } else if (syncStatus === SyncStatus.UPDATE_INSTALLED) {
      console.log("CodePush: update installed - it will be activated upon next cold boot");
    }
});

何时运行此检查？

建议在冷启动周期中多次检查更新，因此最好将此检查与resume事件（通常在应用启动时运行）相关联

import * as application from "tns-core-modules/application";
import { CodePush } from "nativescript-code-push";

// add this in some central place that's executed once in a lifecycle
application.on(application.resumeEvent, () => {
  CodePush.sync(...);
});

var application = require("tns-core-modules/application");

application.on(application.resumeEvent, function () {
  // call the sync function
});

发布更新

一旦你的应用已配置并分发给用户，并且你已经进行了一些代码和/或资源的更改，现在是时候将这些更改立即发布给用户了！

⚠️ 确保首先创建一个发布构建，因此使用你用于应用商店分发的相同命令，但不要将其发送到AppStore。你甚至可以使用Webpack和Uglify你的应用，这对插件来说都是透明的。

💁‍♂️ 当向CodePush发布更新时，你不需要提高应用的版本，因为你根本没有修改应用商店的版本。CodePush将自动为每个发布的发布生成一个“标签”（例如v3），以便帮助你在发布历史中识别它。

最简单的方式是使用我们的CodePush CLI中的release命令。它（最相关的）选项有

以下为两个平台提供了一些示例

iOS

nativescript-code-push release <codepush-ios-appname> ios # deploy to Staging
nativescript-code-push release <codepush-ios-appname> ios --d Production # deploy to Production (default: Staging)
nativescript-code-push release <codepush-ios-appname> ios --targetBinaryVersion ~1.0.0 # release to users running any 1.x version (default: the exact version in Info.plist)
nativescript-code-push release <codepush-ios-appname> ios --mandatory --description "My mandatory iOS version" # a release for iOS that needs to be applied ASAP.

Android

nativescript-code-push release <codepush-android-appname> android # deploy to Staging
nativescript-code-push release <codepush-android-appname> android --d Production # deploy to Production (default: Staging)
nativescript-code-push release <codepush-android-appname> android --targetBinaryVersion ~1.0.0 # release to users running any 1.x version (default: the exact version in AndroidManifest.xml)

了解过去发布的洞察

以下是一些可能对您有用的 CodePush CLI 命令

我创建了哪些发布，以及安装指标是什么？

使用这样的命令将告诉您安装了更新的应用程序数量

nativescript-code-push deployment history <codepush-appname> Staging

产生如下内容

给我当前发布的详细信息！

这将转储应用程序的测试环境和生产环境中最新的发布详情

nativescript-code-push deployment ls <codepush-appname>

如果您还想转储部署密钥，请使用

nativescript-code-push deployment ls <codepush-appname> --displayKeys

产生如下内容

清除发布历史

这不会回滚任何发布，但它清理了历史元数据（在这种情况下是测试应用程序的历史元数据）

nativescript-code-push deployment clear <codepush-appname> Staging

高级主题

在开发期间测试 CodePush 包

在使用生产环境之前，您可能想先玩一玩 CodePush（明智之举！）在推送更新并将 sync 命令添加到应用程序后，执行以下步骤

• $ tns run <platform>。在 iOS 设备 上添加 --release 标志，以便 LiveSync 不会干扰。
• 更新安装后，终止并重新启动应用程序

运行演示应用程序

您还可以通过使用其演示应用程序来玩一玩 CodePush。以下是您需要执行的步骤，以观察应用程序更新

• 注册服务（nativescript-code-push register）并将演示应用程序添加到您的帐户（nativescript-code-push app add <appname> <platform> nativescript）
• 一旦应用程序注册，您将在控制台看到其部署密钥，使用它们更新 demo 中的密钥
• 转到 src 并运行 npm run preparedemo - 这将构建插件并将引用添加到演示应用程序中
• 准备一个用作“更新版本”的应用程序（例如，取消注释其中一个 CODEPUSH 标签并注释 APPSTORE 标签），然后运行 tns build <platform>
• 发布更新（nativescript-code-push release <appname> <platform>）
• 您可以使用 nativescript-code-push deployment history <appname> Staging 确保它出现在更新列表中
• 准备一个用作“官方发布版本”的应用程序（例如，注释 CODEPUSH 标签并取消注释 APPSTORE 标签），然后运行 tns run <platform>
• 当应用程序在设备上部署时，您应该看到“官方发布版本”以及有关已安装更新的信息
• 关闭应用程序（并从设备最近的应用中移除以确保下一次启动为冷启动）然后再次运行它 - 你现在应该能看到应用程序的“更新版本”

修补更新元数据

发布更新后，可能存在需要修改与更新相关的一个或多个元数据属性的情况（例如，你忘记将关键错误修复标记为强制性的）。

nativescript-code-push patch <appName> <deploymentName>
[--label <releaseLabel>]
[--mandatory <isMandatory>]
[--description <description>]
[--targetBinaryVersion <targetBinaryVersion>]

# Mark the latest production release as mandatory
nativescript-code-push patch MyAppiOS Production -m

# Add a "mina and max binary version" to an existing release
nativescript-code-push patch MyAppiOS Staging -t "1.0.0 - 1.0.5"

更新更新

nativescript-code-push promote <appName> <sourceDeploymentName> <destDeploymentName>
[--description <description>]
[--label <label>]
[--mandatory]
[--targetBinaryVersion <targetBinaryVersion]

# example
nativescript-code-push promote CodePushDemoIOS Staging Production --description 'Promoted from Staging to Production'

回滚更新

nativescript-code-push rollback <appName> <deploymentName>

#example
nativescript-code-push rollback MyAppiOS Production

nativescript-code-push rollback MyAppiOS Production --targetRelease v34

应用协作

nativescript-code-push collaborator add <appName> <collaboratorEmail>

nativescript-code-push collaborator rm <appName> <collaboratorEmail>

nativescript-code-push collaborator ls <appName>

在代理后使用CodePush

nativescript-code-push login --noProxy

nativescript-code-push login --proxy https://foo.com:3454