Migration Guide

This is a migration guide for existing Ionic v1 apps. The ionic-platform-web-client is deprecated and being replaced with @ionic/cloud on npm. The update brings a much simpler config system as well as some breaking changes.

---

Note: The Cloud Client is still in beta, and this document may change as new beta releases come out.

---

• We are deprecating the installation of the Cloud Client via bower. The new @ionic/cloud package on npm should be used going forward.
• We are essentially requiring angular 1 apps to use the angular 1 integrations ($ionicPush, etc.) instead of the vanilla ES5 classes (Ionic.Push()).
• We are removing development push (dev_push). We felt it only really brought confusion when setting up push. Our docs will only support setting up native push notifications.
• We are deprecating onRegister, onNotification, and onError from the push configuration. Going forward, the event emitter should be used. See the docs.
• Analytics was removed from the client. A separate analytics solution will be reintroduced soon.
• Our source code is now written in Typescript, but we will still be exporting the bundled Cloud Client as usual.
• We are, however, removing the Promise definition from our bundle and expecting it to be defined globally. It is defined in iOS Safari and Android 4.4.4+ (http://caniuse.com/#feat=promises). For peace of mind, a shim can be installed and included before the Cloud Client, such as es6-promise or bluebird.
• The Angular modules have been consolidated. (ionic.service.core, ionic.service.push, etc. are now ionic.cloud).
• $ionicPushAction was removed
• $ionicPush.getPushPlugin() was removed - use $ionicPush.plugin
• New $ionicCurrentUser (current user object). $ionicUser is now current user object
• Ionic.Core.config.getURL('platform-api') is now $ionicCloudConfig.getURL('api')
• Removed $ionicPush.getPayload(notification) method. Just use notification.payload.
• Ionic.io() has been removed (just remove it from your code)
• Ionic.getService/Ionic.addService/Ionic.removeService have been removed
• persistentStorage angular provider has been removed
• Alpha services migration functionality removed

Steps:

Install the Cloud Client from npm:

$ npm install --save @ionic/cloud

Copy the distribution file into your project (you can delete the lib/ionic-platform-web-client directory):

$ cp node_modules/@ionic/cloud/dist/bundle/ionic.cloud.min.js www/lib

Include it in index.html (delete the existing ionic-platform-web-client include and leave cordova.js commented out):

<script src="lib/ionic-cloud.min.js"></script>

With the new config system, you now have to manually supply the config. In app.js, fill in your app id (and gcm key if you’re using push). Don’t forget to change the module names from ionic.service.core, ionic.serve.push, etc. to just ionic.cloud. As for your .io-config.json file, we recommend deleting it. It is no longer necessary.

angular.module('my-app', ['ionic', 'ionic.cloud'])

.config(function($ionicCloudProvider) {
  $ionicCloudProvider.init({
    "core": {
      "app_id": "YOUR-APP-ID",
      "gcm_key": "1234567890"
    }
  });
})

Push Changes

Along with deprecating dev push, we removed onRegister, onNotification, and onError from the push configuration. These events are now handled by the event emitter. The event names are push:register, push:notification, and push:error.

Here’s how you can subscribe to events:

$ionicEventEmitter.on('push:notification', function(data) {
  console.log(data.message);
});

Deploy Changes

Because we switched to using standard Promise objects, the progress notification must be done a way other than a third callback of the then function. $ionicDeploy.download(), $ionicDeploy.extract(), and $ionicDeploy.update() all take an option for an onProgress callback:

$scope.doUpdate = function() {
  function onProgress(p) {
    console.log("deploy progress (0 to 100):", p);
  }

  $ionicDeploy.update({'onProgress': onProgress}).then(function(res) {
    console.log("deploy finished!", res);
  }, function(err) {
    console.log("deploy error", err);
  });
};