Deploy

Summary

Live deployments let you publish web assets such as HTML, JS, and CSS directly to your users without going through the app store.

This lets you:

  • Update your application on demand
  • Skip app store approvals
  • Get new features and bug fixes to your users quickly
  • A/B test by uploading different snapshots to different deploy channels

Terminology

  • Snapshot: A bundled version of your app code. Snapshots can be deployed to devices, letting you switch between different versions of your app, or quickly rollback to a previous version.
  • Live Deployment: When a snapshot is downloaded and activated in a device.
  • Channel: Snapshots are deployed to deploy channels. Channels give you the ability to deploy different snapshots of your app to different devices. Channels have a name and tag. When you reference a channel, use the tag, which is a machine name provided in the case that the name is complex or was changed.
  • Active Channel: The channel Deploy checks for new snapshots and downloads them from. See Changing the Active Channel. Defaults to production.
  • Binary Update: When your app is updated through the app store. Binary Updates are still necessary for binary changes such as changing your Cordova platform version or adding a Cordova plugin or native library.

Prerequisites

Setup

Plugin Installation

You’ll need to install our deploy plugin, which updates your app on Android and iOS devices.

$ cordova plugin add ionic-plugin-deploy --save

Injecting Deploy

Import Deploy from the Cloud Client and specify it as a dependency in your component constructor.

import {Component} from [email protected]/core';
import {Deploy} from [email protected]/cloud-angular';

@Component( ... )
export class MyPage {
  constructor(public deploy: Deploy) {
    ...
  }
}

Specify ionic.cloud as a dependency for your module. This gives you access to $ionicDeploy.

angular.module('myapp.controllers', ['ionic.cloud'])

.controller('MyCtrl', function($scope, $ionicDeploy) {
  ...
})

Channels

Deploy channels give you the ability to deploy different snapshots of your app to different devices.

There are three channels available for every app by default: production, staging, and dev. You can create more channels if needed. By default, Deploy will check for new snapshots and download them from the production channel (production is the active deploy channel by default).

Snapshots

Snapshots are created by uploading a bundled version of your app code using the Ionic CLI. These snapshots can then be deployed to different channels, and ultimately applied to a user’s device.

In the following examples, fill in the following:

NOTE A short description of this snapshot
CHANNEL_TAG production, staging, dev, or a tag of a custom channel

Whenever you’re ready to create a snapshot of your application, run the upload command:

$ ionic upload --note "NOTE"

This will bundle your local app code and upload it as a unique snapshot.

Deploying to Channels

When you upload with the --deploy flag, your snapshot is immediately deployed to a channel. You can alternatively use the Dashboard to deploy snapshots that have been uploaded.

$ ionic upload --note "NOTE" --deploy CHANNEL_TAG

App Implementation

Unlike traditional app store updates, you must implement live deployment code where it makes sense for your app. In general, your app will need to perform the following steps to utilize live deployments:

Check for a New Snapshot

When check() is called, Deploy checks for a new snapshot on the active deploy channel.

this.deploy.check().then((snapshotAvailable: boolean) => {
  if (snapshotAvailable) {
    // When snapshotAvailable is true, you can apply the snapshot
  }
});
$ionicDeploy.check().then(function(snapshotAvailable) {
  if (snapshotAvailable) {
    // When snapshotAvailable is true, you can apply the snapshot
  }
});

Apply the New Snapshot

If a new snapshot is available, you can download and extract it, which will set it as the active snapshot. The next time the app is loaded, the new snapshot will be used.

this.deploy.download().then(() => {
  return this.deploy.extract();
});
$ionicDeploy.download().then(function() {
  return $ionicDeploy.extract();
});

Reload the App

After extract() resolves, you can optionally force an immediate app restart using load().

this.deploy.load();
$ionicDeploy.load();

Changing the Active Channel

By default, Deploy will check for new snapshots and download them from the production channel. In order to download snapshots from other channels, you’ll need to set the channel attribute. Each channel has a unique tag that is used to reference the channel.

this.deploy.channel = 'dev';
$ionicDeploy.channel = 'dev';

If you set an invalid channel or the channel no longer exists, Deploy automatically falls back to the production channel.

Managing Snapshots

Listing

The list of snapshots that are currently stored on the device is not ordered consistently.

this.deploy.getSnapshots().then((snapshots) => {
  // snapshots will be an array of snapshot uuids
});
$ionicDeploy.getSnapshots().then(function(snapshots) {
  // snapshots will be an array of snapshot uuids
});

Removing

You can remove unwanted snapshots to free up space on the device.

this.deploy.deleteSnapshot('366f119a-4d3b-46fd-b1be-1def98812344');
$ionicDeploy.deleteSnapshot('366f119a-4d3b-46fd-b1be-1def98812344');

Make sure you do not delete the active snapshot or your app will become unusable.

Metadata

Metadata allows you to set custom key/value pairs that you can use to provide custom data to your deployments.

this.deploy.check().then((hasUpdate: boolean) => {
  if (hasUpdate) {
    this.deploy.getMetadata().then((metadata) => {
      // use metadata
    });
  }
});
$ionicDeploy.check().then(function(hasUpdate) {
  if (hasUpdate) {
    $ionicDeploy.getMetadata().then(function(metadata) {
      // use metadata
    });
  }
});

Getting metadata for a specific deploy

If you wish to get the metadata for a specific snapshot, you can pass the snapshot UUID.

this.deploy.getMetadata('366f119a-4d3b-46fd-b1be-1def98812344').then((metadata) => {
  // use metadata
});
$ionicDeploy.getMetadata('366f119a-4d3b-46fd-b1be-1def98812344').then(function(metadata) {
  // use metadata
});

Binary Versioning

You can determine if a snapshot is applicable for a device by using binary versioning. Binary versioning requires that you use a semantic version for your build version.

The semantic versioning format is a common strategy for flexible and predictable versioning. The format comprises three parts, major.minor.patch. When we compare versions, we adhere to version precedence. Example: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1.

As you develop your app, you may need to add or update Cordova plugins, update the platform sdk support, or make other changes that would require a binary update. If you deploy a snapshot of your app expecting such changes, your app may crash. Binary versioning lets you halt live deployments on devices that would otherwise break the app.

There are three mechanisms you can use for both iOS and Android:

Minimum Only perform the deploy if the installed version is equal or higher. Set this when you introduce binary changes to your app.
Maximum Only perform the deploy if the installed version is equal or lower. Set this when you have different major versions on multiple channels and you need to deploy to older binary versions.
Equivalent Do not perform the deploy if the installed version is equivalent. Set this when you publish the version to the app store. This is for effectively ignoring unnecessary live deployments.

FAQ

I’ve set a deploy channel, but it isn’t looking for updates in the channel I set.

You need to make sure you’ve set the correct channel tag. If you used the channel name or do not use the exact tag name it will fallback to the production channel.

Services

    API

      General