Skip to content
This repository has been archived by the owner on Oct 1, 2018. It is now read-only.

Listen for update events

Nikolay Demyankov edited this page Apr 25, 2016 · 1 revision

Using JavaScript you can subscribe to different update related events. For example, you can get notified when update is loaded and ready for installation, or when something went wrong and we couldn't install new content.

You subscribe for events as you normally do like so:

  document.addEventListener(eventName, eventCallback, false);

  function eventCallback(eventData) {
    // do something
  }

Error events have details on what went wrong. You can access them like so:

function eventCallback(eventData) {
  var error = eventData.details.error;
  if (error) {
    console.log('Error with code: ' + error.code);
    console.log('Description: ' + error.description);
  }
}

Available events are:

  • chcp_updateIsReadyToInstall - sent when new release was successfully loaded and ready to be installed.
  • chcp_updateLoadFailed - sent when plugin couldn't load update from the server. Error details are attached to the event.
  • chcp_nothingToUpdate - sent when we successfully loaded application config from the server, but there is nothing new is available.
  • chcp_beforeInstall - sent when an update is about to be installed.
  • chcp_updateInstalled - sent when update was successfully installed.
  • chcp_updateInstallFailed - sent when update installation failed. Error details are attached to the event.
  • chcp_nothingToInstall - sent when there is nothing to install. Probably, nothing was loaded before that.
  • chcp_beforeAssetsInstalledOnExternalStorage - sent when plugin is about to start installing bundle content on the external storage.
  • chcp_assetsInstalledOnExternalStorage - sent when plugin successfully copied web project files from bundle on the external storage. Most likely you will use it for debug purpose only. Or even never.
  • chcp_assetsInstallationError - sent when plugin couldn't copy files from bundle on the external storage. If this happens - plugin won't work. Can occur when there is not enough free space on the device. Error details are attached to the event.

Now it is time for small example. Lets say that you have an index.js file, which is included in the header of your index.html page.

var app = {

  // Application Constructor
  initialize: function() {
    this.bindEvents();
  },

  // Bind any events that are required.
  // Usually you should subscribe on 'deviceready' event to know, when you can start calling cordova modules
  bindEvents: function() {
    document.addEventListener('deviceready', this.onDeviceReady, false);
  },

  // deviceready Event Handler
  onDeviceReady: function() {
    console.log('Device is ready for work');
  }
};

app.initialize();

It is very similar to the default index.js file which is generated by Cordova when you create your project. In order to get notified when plugin loads new release - you need to subscribe on chcp_updateIsReadyToInstall event like so:

bindEvents: function() {
  // ...some other events subscription code...

  document.addEventListener('chcp_updateIsReadyToInstall', this.onUpdateReady, false);
},

and add event handler:

// chcp_updateIsReadyToInstall Event Handler
onUpdateReady: function() {
  console.log('Update is ready for installation');
}

The resulting index.js will be:

var app = {

  // Application Constructor
  initialize: function() {
    this.bindEvents();
  },

  // Bind any events that are required.
  // Usually you should subscribe on 'deviceready' event to know, when you can start calling cordova modules
  bindEvents: function() {
    document.addEventListener('deviceready', this.onDeviceReady, false);
    document.addEventListener('chcp_updateIsReadyToInstall', this.onUpdateReady, false);
  },

  // deviceready Event Handler
  onDeviceReady: function() {
    console.log('Device is ready for work');
  },

  // chcp_updateIsReadyToInstall Event Handler
  onUpdateReady: function() {
    console.log('Update is ready for installation');
  }
};

app.initialize();

From now on we will know, when update is loaded and ready for installation. By using JavaScript module we can force the plugin to install the update right now, even if it was meant to be installed on the next launch.

Clone this wiki locally