{"_id":"56d1f33a00a2a70b00b365d1","user":"5526ca4cf69851170038b496","project":"5526c95cf69851170038b48f","__v":11,"version":{"_id":"56d1f33700a2a70b00b3658e","project":"5526c95cf69851170038b48f","__v":2,"createdAt":"2016-02-27T19:04:23.946Z","releaseDate":"2016-02-27T19:04:23.946Z","categories":["56d1f33900a2a70b00b3658f","56d1f33900a2a70b00b36590","56d1f33900a2a70b00b36591","56d1f33900a2a70b00b36592","56d1f33900a2a70b00b36593","56d1f33900a2a70b00b36594","56d1f33900a2a70b00b36595","56d1f33900a2a70b00b36596","56d1f33900a2a70b00b36597","56d1f33900a2a70b00b36598","56d1f33900a2a70b00b36599","56d1f33900a2a70b00b3659a","571f9497ada30c34003b7cee"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"beta","version_clean":"2.0.0-beta","version":"2.0.0-beta"},"parentDoc":null,"category":{"_id":"56d1f33900a2a70b00b3658f","version":"56d1f33700a2a70b00b3658e","__v":1,"pages":["56d1f33a00a2a70b00b365c1","56d1f33a00a2a70b00b365c2","56d1f33a00a2a70b00b365c3","56d1f33a00a2a70b00b365c4","56d1f33a00a2a70b00b365c5","56d1f33a00a2a70b00b365c6","56d1f33a00a2a70b00b365c7","56d1f33a00a2a70b00b365c8","56d1f33a00a2a70b00b365c9","56d1f33a00a2a70b00b365ca","56d1f33a00a2a70b00b365cb","56d1f33a00a2a70b00b365cc","56d1f33a00a2a70b00b365cd","56d1f33a00a2a70b00b365ce","56d1f33a00a2a70b00b365cf","56d1f33a00a2a70b00b365d0","56d1f33a00a2a70b00b365d1","56d1f33a00a2a70b00b365d2"],"project":"5526c95cf69851170038b48f","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-04-10T13:13:56.755Z","from_sync":false,"order":0,"slug":"getting-started","title":"Getting Started"},"updates":["57287dec90a5580e004191fd"],"next":{"pages":[],"description":""},"createdAt":"2015-12-03T14:00:48.794Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":6,"body":"[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"The Ionic Platform has now moved to Beta status. Part of this change is the introduction of the Platform API and User authentication. We've deprecated the alpha API for the Users and Push services and will be removing them entirely in the coming months.\",\n  \"title\": \"Deprecation Warning\"\n}\n[/block]\n## Breaking Changes\n\nYou'll need to migrate your application if you are currently using Ionic Users or Ionic Push.\n\n* Users now require Authentication\n* Users has a new API\n* Push has a new API\n* Deploy requires a plugin update\n\n## Platform Web-Client Update\n\nThe beta requires the installation of the latest `ionic-platform-web-client`. Run the following command to install the platform web client in your app:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ ionic add ionic-platform-web-client\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n## API Changes\n\nThe platform beta has introduced a new host for API access:\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"https://api.ionic.io\"\n}\n[/block]\nThe new API uses [JSON Web Tokens](https://en.wikipedia.org/wiki/JSON_Web_Token) to authenticate requests, and will be the standard for the Platform moving forward. We'll  steadily move all our current API's into this new system, but currently we have only moved our Users and Push APIs.\n\nMaking authenticated requests to the api will require the `Authorization` header. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET -H \\\"Authorization: Bearer YOUR_TOKEN\\\" https://api.ionic.io/auth/test\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nYou can now expect consistently structured JSON responses that contain either a `data` or `error` property alongside a `meta` property:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"data\\\": {\\n    \\\"success\\\": \\\"You have successfully made an authenticated request to the Ionic Platform API\\\"\\n  },\\n  \\\"meta\\\": {\\n    \\\"version\\\": \\\"1.0.0\\\",\\n    \\\"status\\\": 200,\\n    \\\"request_id\\\": \\\"9066c8c3-948e-4560-bb8b-bafc04d226b7\\\"\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n## User Changes\n\n`Ionic.User` now requires the implementation of `Ionic.Auth` into your application. Check out the [User Overview](doc:user-overview) docs to get setup. You now no longer add device tokens via the User object -- see the push changes below.\n\nAny external services interacting with the Users API will now need to adhere to the new [User API](doc:api-users) endpoints.\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Removed Methods\",\n  \"body\": \"addPushToken\\nremovePushToken\"\n}\n[/block]\n**Migrating User Data**\n\nThe new User API has no ties to the old API and therefore you will need to migrate your existing user data after you register a user. We have provided a `migrate` method that can be called after successfully authenticating a user. This will migrate any legacy user data on the device to the new authenticated user:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// use `migrate` in your Ionic.Auth.login success callback\\nvar authSuccess = function(user) {\\n  user.migrate(); // sets legacy user data on the new auth'd user\\n  user.save();    // save the user to persist the migration changes\\n};\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n## Push Changes\n\nThere is a brand new [Push API](doc:api-push) for interacting with the service. Any external services interacting with the API will need to adhere to the new [Push API](doc:api-push) endpoints. \n\nPush now uses security profiles to manage the APNs and GCM credentials, so you'll really want to read the [Push Overview](doc:push-overview) again to see how everything fits together.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Saving Device Tokens\",\n  \"body\": \"Previously, device tokens were only saved if you added them to a user, or sent raw tokens to the Push API. Now you only need to call `saveToken` which will save the token and automatically tie it to the currently authenticated User. See the example below:\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var push = new Ionic.Push();\\n\\npush.register(function(token) {\\n\\tpush.saveToken(token);\\n});\\n\\n/*\\n\\nIf you do NOT want the currently authenticated User to be tied to the Token, you can pass the 'ignore_user' option like so.\\n\\n\\tpush.saveToken(token, { 'ignore_user': true });\\n\\n*/\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Removed Methods\",\n  \"body\": \"addTokenToUser\"\n}\n[/block]\n## Deploy Changes\n\nDeploy requires a binary plugin update to continue functioning past the close date of our alpha services. You will need to have version `0.5.0` (or greater) of the plugin installed on end-user devices by that time. The plugin requires version `0.7.1` or greater of the `ionic-platform-web-client` to function.\n\nTo install the latest plugin, run `ionic plugin rm ionic-plugin-deploy` and then add the latest version with `ionic plugin add ionic-plugin-deploy`. \n\nYou can verify your plugin version with `ionic plugin info`, and verify the web client version with `bower list`.","excerpt":"This covers the changes you will need to make if you have an existing app using Users or Push services.","slug":"migration-guide","type":"basic","title":"Beta Migration"}

Beta Migration

This covers the changes you will need to make if you have an existing app using Users or Push services.

[block:callout] { "type": "danger", "body": "The Ionic Platform has now moved to Beta status. Part of this change is the introduction of the Platform API and User authentication. We've deprecated the alpha API for the Users and Push services and will be removing them entirely in the coming months.", "title": "Deprecation Warning" } [/block] ## Breaking Changes You'll need to migrate your application if you are currently using Ionic Users or Ionic Push. * Users now require Authentication * Users has a new API * Push has a new API * Deploy requires a plugin update ## Platform Web-Client Update The beta requires the installation of the latest `ionic-platform-web-client`. Run the following command to install the platform web client in your app: [block:code] { "codes": [ { "code": "$ ionic add ionic-platform-web-client", "language": "shell" } ] } [/block] ## API Changes The platform beta has introduced a new host for API access: [block:callout] { "type": "info", "title": "https://api.ionic.io" } [/block] The new API uses [JSON Web Tokens](https://en.wikipedia.org/wiki/JSON_Web_Token) to authenticate requests, and will be the standard for the Platform moving forward. We'll steadily move all our current API's into this new system, but currently we have only moved our Users and Push APIs. Making authenticated requests to the api will require the `Authorization` header. [block:code] { "codes": [ { "code": "curl -X GET -H \"Authorization: Bearer YOUR_TOKEN\" https://api.ionic.io/auth/test", "language": "curl" } ] } [/block] You can now expect consistently structured JSON responses that contain either a `data` or `error` property alongside a `meta` property: [block:code] { "codes": [ { "code": "{\n \"data\": {\n \"success\": \"You have successfully made an authenticated request to the Ionic Platform API\"\n },\n \"meta\": {\n \"version\": \"1.0.0\",\n \"status\": 200,\n \"request_id\": \"9066c8c3-948e-4560-bb8b-bafc04d226b7\"\n }\n}", "language": "json" } ] } [/block] ## User Changes `Ionic.User` now requires the implementation of `Ionic.Auth` into your application. Check out the [User Overview](doc:user-overview) docs to get setup. You now no longer add device tokens via the User object -- see the push changes below. Any external services interacting with the Users API will now need to adhere to the new [User API](doc:api-users) endpoints. [block:callout] { "type": "danger", "title": "Removed Methods", "body": "addPushToken\nremovePushToken" } [/block] **Migrating User Data** The new User API has no ties to the old API and therefore you will need to migrate your existing user data after you register a user. We have provided a `migrate` method that can be called after successfully authenticating a user. This will migrate any legacy user data on the device to the new authenticated user: [block:code] { "codes": [ { "code": "// use `migrate` in your Ionic.Auth.login success callback\nvar authSuccess = function(user) {\n user.migrate(); // sets legacy user data on the new auth'd user\n user.save(); // save the user to persist the migration changes\n};", "language": "javascript" } ] } [/block] ## Push Changes There is a brand new [Push API](doc:api-push) for interacting with the service. Any external services interacting with the API will need to adhere to the new [Push API](doc:api-push) endpoints. Push now uses security profiles to manage the APNs and GCM credentials, so you'll really want to read the [Push Overview](doc:push-overview) again to see how everything fits together. [block:callout] { "type": "info", "title": "Saving Device Tokens", "body": "Previously, device tokens were only saved if you added them to a user, or sent raw tokens to the Push API. Now you only need to call `saveToken` which will save the token and automatically tie it to the currently authenticated User. See the example below:" } [/block] [block:code] { "codes": [ { "code": "var push = new Ionic.Push();\n\npush.register(function(token) {\n\tpush.saveToken(token);\n});\n\n/*\n\nIf you do NOT want the currently authenticated User to be tied to the Token, you can pass the 'ignore_user' option like so.\n\n\tpush.saveToken(token, { 'ignore_user': true });\n\n*/", "language": "javascript" } ] } [/block] [block:callout] { "type": "danger", "title": "Removed Methods", "body": "addTokenToUser" } [/block] ## Deploy Changes Deploy requires a binary plugin update to continue functioning past the close date of our alpha services. You will need to have version `0.5.0` (or greater) of the plugin installed on end-user devices by that time. The plugin requires version `0.7.1` or greater of the `ionic-platform-web-client` to function. To install the latest plugin, run `ionic plugin rm ionic-plugin-deploy` and then add the latest version with `ionic plugin add ionic-plugin-deploy`. You can verify your plugin version with `ionic plugin info`, and verify the web client version with `bower list`.