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 services ($ionicPush, etc.) instead of the vanilla ES5 classes (Ionic.Push). We changed how these classes were instantiated (by using dependency injection), and thus doing new Ionic.Push() et al. will simply not work.
• 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 "return" values of promises have changed across the services. Most success handlers don't give any parameters (because they didn't need to) and all error handlers now return an Error instance.
• 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.
• Removed current(), resetPassword(), isAuthenticated(), isFresh(), isDirty() methods on $ionicUser. See below.
• Removed onReady() method of all services. Check out the events you can subscribe to with the new event emitter.
• 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"
    }
  });
})

User Changes

In an attempt to make things much easier for the majority of developers, some breaking changes were made for Ionic User. Instead of having a single User class that has everything, we've enforced a single reference to the current user and made it seem more like a model. The User class uses a service class underneath the hood that manages the single reference, making it easier on you.

Removed methods:

• current() - $ionicUser will now always be a reference to the current user, whether that user is anonymous, authenticated, etc.
• resetPassword() - TODO
• isAuthenticated() - Use $ionicAuth.isAuthenticated() to see if the current user is authenticated
• isFresh() - Just use the property $ionicUser.fresh, which is a boolean
• isDirty() - This method basically let you know if a save failed. Just utilize the promise returned from $ionicUser.save()
• self() - Just use load() without passing an ID.

The load(id), save(), and delete() methods all exist on $ionicUser and all update the $ionicUser reference. They no longer "return" values in the success handler.

Auth Changes

• The last two parameters of login have been swapped (options is now last so that it may be excluded, because options are optional). For example, instead of login('basic', {'remember': true}, details), it's login('basic', details, {'remember': true})
• The 'remember': true option is now the default. You can pass {'remember': false} if you want the user session to persist in session storage instead of local storage.

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

$ionicPush.register now uses a promise, not a callback (to be consistent). Here's how to register and save a token:

$ionicPush.register().then(function(token) {
  return $ionicPush.saveToken(token);
}).then( ... );

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