NativeScript plugin for CodePush

A live-update service for your NativeScript apps!

📣 UPDATE May 27 2019: we're most likely renaming this solution before officially launching it. Hold your breath!

Optional reading: what this is, and how it works

A NativeScript app is composed of XML/HTML, CSS and JavaScript files and any accompanying images, which are bundled together by the NativeScript CLI and distributed as part of a platform-specific binary (i.e. an .ipa or .apk file). Once the app is released, updating either the code (e.g. making bug fixes, adding new features) or image assets, requires you to recompile and redistribute the entire binary, which of course, includes any review time associated with the store(s) you are publishing to.

The CodePush plugin helps get product improvements in front of your end users instantly, by keeping your code and images synchronized with updates you release to the CodePush server. This way, your app gets the benefits of an offline mobile experience, as well as the "web-like" agility of side-loading updates as soon as they are available. It's a win-win!

In order to ensure that your end users always have a functioning version of your app, the CodePush plugin maintains a copy of the previous update, so that in the event that you accidentally push an update which includes a crash, it can automatically roll back. This way, you can rest assured that your newfound release agility won't result in users becoming blocked before you have a chance to roll back on the server. It's a win-win-win!

Architectural overview of the solution - you don't need to worry about all of this

What can (and will) be CodePushed?

• Anything inside your /app folder.
• Anything inside your /node_modules folder.

💁‍♂️ Note that we don't actually use those folders, but the app folder in platforms/ios/<appname>/app and platforms/android/app/src/main/assets/app, the benefit of which is we don't "care" if you use Webpack or Uglify or whatever tools you use to minify or scramble your app's assets.

What can't (and won't):

• NativeScript platform updates. Example: bumping tns-android from version 2.5.1 to 2.5.2.
• Plugins updates that also require a different version of a native library it depends on.

So as long as you don't change versions of dependencies and tns platforms in your package.json you can push happily. And if you do bump a version of a dependency make sure there are no changed platform libraries.

Getting Started

Globally install the NativeScript CodePush CLI

npm i -g nativescript-code-push-cli

💁‍♂️ This will also add the global nativescript-code-push command to your machine. You can check the currently installed version with nativescript-code-push -v.

Login or register with the service

Check if you're already logged in, and with which email address:

nativescript-code-push whoami

Log in if you already have an account:

nativescript-code-push login

Register if you don't have an account yet:

nativescript-code-push register

This will open a browser where you can provide your credentials, after which you can create an access key that you can paste in the console.

You should now have a .nativescript-code-push.config file in your home folder which will automatically authenticate you with the server on this machine from now on.

Note that you could use a that web interface for managing you apps, but the CLI is much more sophisticated, so it's recommended to use the command line interface.

To log out, you can run nativescript-code-push logout which will also remove the config file.

To perform a headless login (without opening a browser), you can do: nativescript-code-push login --accessKey <access key>.

Register your app with the service

Create an app for each platform you target. That way you can roll out release seperately for iOS and Android.

⚠️ The appname must be unique, and should not contain dashes (-).

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

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

💁‍♂️ This will show you your deployment keys you'll need when connecting to the CodePush server. If you want to list those keys at any later time, use nativescript-code-push deployment ls <appName> --displayKeys.

💁‍♂️ All new apps automatically come with two deployments (Staging and Production) so that you can begin distributing updates to multiple channels. If you need more channels/deployments, simply run: nativescript-code-push deployment add <appName> <deploymentName>.

💁‍♂️ Want to rename your app? At any time, use the command: nativescript-code-push app rename <oldName> <newName>

💁‍♂️ Want to delete an app? At any time, use the command: nativescript-code-push app remove <appName> - this means any apps that have been configured to use it will obviously stop receiving updates.

List your registered apps

nativescript-code-push app ls

Add this plugin to your app

tns plugin add nativescript-code-push

⚠️ If you're restricting access to the internet from within your app, make sure you whitelist our CodePush server (https://nativescript-codepush-server.herokuapp.com) and File server (https://s3.eu-west-1.amazonaws.com).

Checking for updates

With the CodePush plugin installed and configured, the only thing left is to add the necessary code to your app to control when it checks for updates.

If an update is available, it will be silently downloaded, and installed.

Then based on the provided InstallMode the plugin either waits until the next cold start (InstallMode.ON_NEXT_RESTART), warm restart (InstallMode.ON_NEXT_RESUME), or a positive response to a user prompt (InstallMode.IMMEDIATE).

Note that Apple doesn't want you to prompt the user to restart your app, so use InstallMode.IMMEDIATE on iOS only for Enterprise-distributed apps (or when testing your app through TestFlight for instance).

💁‍♂️ Check out the demo for a solid example.

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

There's a few things you can configure - this TypeScript example has all the possible options:

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

When should this check run?

It's recommended to check for updates more than once in a cold boot cycle, so it may be easiest to tie this check to the resume event (which usually also runs on app startup):

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

Releasing an update

Once your app has been configured and distributed to your users, and you've made some code and/or asset changes, it's time to instantly unleash those changes onto your users!

⚠️ Make sure to create a release build first, so use the same command that you'd use for app store distribution, just don't send it to the AppStore. You can even Webpack and Uglify your app, it's all transparent to this plugin.

💁‍♂️ When releasing updates to CodePush, you do not need to bump your app's version since you aren't modifying the app store version at all. CodePush will automatically generate a "label" for each release you make (e.g. v3) in order to help identify it within your release history.

The easiest way to do this is to use the release command in our CodePush CLI. Its (most relevant) options are:

Have a few examples for both platforms:

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)

Gaining insight in past releases

Here are a few CodePush CLI commands you may find useful:

Which releases did I create and what are the install metrics?

Using a command like this will tell you how many apps have the update installed:

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

Which produces something like this:

Give me the details of the current release!

This dumps the details of the most recent release for both the Staging and Production environments of your app:

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

And if you want to dump your deployment keys as well, use:

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

Which produces something like this:

Clearing the release history

This won't roll back any releases, but it cleans up the history metadata (of the Staging app, in this case):

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

Advanced topics

Testing CodePush packages during development

You may want to play with CodePush before using it in production (smart move!). Perform these steps once you've pushed an update and added the sync command to your app:

• $ tns run <platform>. On an iOS device add the --release flag so LiveSync doesn't interfere.
• kill and restart the app after the update is installed

Running the demo app

You may also play with CodePush by using its demo app. Here are the steps you need to perform in order to observe an app update:

• register with the service (nativescript-code-push register) and add the demo app to your account (nativescript-code-push app add <appname> <platform> nativescript)
• once the app is registered you will see its deployment keys in the console, use them to update the ones in the demo
• go to src and run npm run preparedemo - this will build the plugin and add a reference to the demo app
• prepare an app that will be used as an "update version" (for example, uncomment one of the CODEPUSH labels and comment the APPSTORE label), then run tns build <platform>
• release the update (nativescript-code-push release <appname> <platform>)
• you can ensure it appears in the list with updates (nativescript-code-push deployment history <appname> Staging)
• prepare an app that will be used as an "official release version" (for example, comment the CODEPUSH label and uncomment the APPSTORE label), then run tns run <platform>
• when the app is deployed on the device, you should see the "official release version" along with information about an installed update
• close the app (and remove it from device's recent apps to ensure its next start will be a cold start) and run it again - you should now see the "update version" of the app

Patching Update Metadata

After releasing an update, there may be scenarios where you need to modify one or more of the metadata attributes associated with it (e.g. you forgot to mark a critical bug fix as mandatory.

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"

Promoting Updates

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'

Rolling Back Updates

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

#example
nativescript-code-push rollback MyAppiOS Production

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

App Collaboration

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

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

nativescript-code-push collaborator ls <appName>

Using CodePush behind a proxy

nativescript-code-push login --noProxy

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