{"_id":"56d5984cf612b80b00fb6997","__v":10,"category":{"_id":"56d1f33900a2a70b00b36592","project":"5526c95cf69851170038b48f","version":"56d1f33700a2a70b00b3658e","pages":["56d1f33b00a2a70b00b365d3","56d1f33b00a2a70b00b365d4","56d1f33b00a2a70b00b365d5","56d1f33b00a2a70b00b365d6","56d1f33b00a2a70b00b365d7","56d1f33b00a2a70b00b365d8","56d1f33b00a2a70b00b365d9","56d1f33b00a2a70b00b365da","56d1f33b00a2a70b00b365db","56d1f33b00a2a70b00b365dc","56d5984cf612b80b00fb6997"],"__v":2,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-04-10T15:43:12.697Z","from_sync":false,"order":2,"slug":"ionic-user","title":"Ionic User"},"parentDoc":null,"project":"5526c95cf69851170038b48f","user":"5526ca4cf69851170038b496","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"},"updates":["57259450d10d5e0e00faa97b","5746dc1e43217220005056a1","578d7c46ec8b4434007c82be"],"next":{"pages":[],"description":""},"createdAt":"2016-03-01T13:25:32.171Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"A fundamental component of most applications is the concept of a user account. This is almost always accompanied by some form of registration, and ultimately an authentication process. That's why we have built these components for use in your app, we call this Ionic Auth and Ionic Users interchangeably, but they are slightly distinct concepts that work in tandem. \n\nLet's discuss the concepts of each of these components individually and then talk about how they are most useful when combined.\n\n* [User Registration](#user-registration)\n* [Authentication](#authentication)\n* [User Data](#user-data)\n* [Bringing it all together](#bringing-it-all-together)\n* [Useful Methods](#useful-methods)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"User Registration\"\n}\n[/block]\nMost of you should already be familiar with the user registration process, after all, you went through the process signing up at [apps.ionic.io](https://apps.ionic.io). A registration process typically asks you to fill out a few simple details like your name, e-mail, and potentially a username, which is then used to create a *unique* account for the user who filled out the details. The application can then store those details for later use with that account. \n\nThis is also called a *signup* or *account creation*. Sometimes the details given conflict with an existing account, and the user will need to provide different information (perhaps the user actually already had an account!).\n\nNo matter the name or process used to ask for information, the end result is the same in Ionic.Auth, a **User** is created and assigned a unique id.\n\nSimple, right?\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Authentication\"\n}\n[/block]\nTypically an application has some form of authentication process (you may be more familiar with the term *login* or *sign up*) when the application starts. There are many different ways to do this, but typically you'll see a username and password prompt, or maybe a button that says *Login with Twitter*. These two examples actually behave very differently in most cases as the former usually authentications with the current application, while the latter authenticates with a 3rd party. \n\nThe process you use to authenticate does not tend to change the purpose of authenticating, which is to verify a *user* is who he or she says they are. \n\nThe basic idea is that only the person attempting to authenticate should know the specific details (email/password for example) of the account they want to use.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"User Data\"\n}\n[/block]\nThere are millions of different reasons to want/need user data in your app, but we will work off the basic idea that your app needs to store user preferences.\n\nLet's say your app has a light and a dark theme that you want your users to be able to select between at will. Pretend for a moment that you have a limited concept of a user, which is essentially *whoever happens to be using this device at this time*. You could easily store the theme preference in localStorage and would easily be able to read the preference each time the application opens, but what happens when the device is shared between multiple people (perhaps this is an iPad used by a family).\n\nAssuming each person has their own preference for which theme to use, it's likely that each time they open your app they will need to reset the theme preference. What about if they buy another device, or want to use the app on their phones? Now they have to manage their preferences between multiple devices...\n\nWith such a basic example I'm sure you could think of a way to get around this, but instead let's talk about what would happen if each *person* had an account with your app. If you stored the preference with the account, you can now share the same preference across multiple devices, and each user would only need to enter their preference one time! \n\nSo, that's just one basic example, but the main idea here is that each user can have their own set of data that your app can read from. This doesn't need to be just user preferences, you could store contact information, birthdates, data for interacting with other systems, or maybe something more complex like user reminders.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Bringing it all together\"\n}\n[/block]\nSo we've talked about each of the different concepts, now let's talk about how we utilize each of these steps using `Ionic.Auth` and `Ionic.User`\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"For brevity, we will not be covering how to collect data from the user in the signup and login steps, but will instead just focus on using the pre-collected data with the platform web client.\"\n}\n[/block]\nThe first thing we want someone to do in our app is to signup. We'll do this with basic authentication. Basic authentication uses an e-mail and password to login so that's what we need to collect first:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var details = {\\n  'email': 'example:::at:::example.com',\\n  'password': 'secretpassword'\\n};\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nNow that we've collected some details we can attempt to signup:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Ionic.Auth.signup(details).then(signupSuccess, signupFailure);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n`signupSuccess` and `signupFailure` are success and failure callbacks respectively. You can learn more about how to handle errors [here](doc:user-authentication#section-handling-registration-errors), but we'll assume that the signup was successful for now.\n\nNow we have a user account created with the details we collected previously. The user will no longer need to signup again.\n\nHowever, now we need the user to login:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var options = { 'remember': true };\\nIonic.Auth.login('basic', options, details).then(authSuccess, authFailure);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nLet's talk about those two lines a bit more:\n\nThe first line is just an object that contains options for the login. Currently, the only key available is `remember`, which is a boolean value to determine if the user should remain logged after they close the app.\n\nThe second line has a bit more going on, the first thing to note is that we are calling `Ionic.Auth.login`. This is the method you will always use to login. The first parameter is the type of authentication to use. In our case we are using `basic` authentication. There are several other types but we will not be covering them here. Check out the [Authentication](doc:user-authentication) page for more information.\n\nThe 2nd and 3rd parameters just use the previously defined data, and finally we use `authSuccess` and `authFailure` which are callbacks for success and failure. You'll want to replace those with your own methods. Check out our [basic example](doc:user-authentication#section-basic-example) for a more complete example.\n\nNow we have successfully authenticated the user. You can now interact with the current user as normal. See the [Usage](doc:user-usage) page for more details on what you can do with a user, but for now we'll just talk about some key methods you'll want to take advantage of...\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Useful Methods\"\n}\n[/block]\nAlright, we've shown you how to register and login, and the [user usage](doc:user-usage) page discusses the user methods, but let's cover a typical usage you'll want to use in your app.\n\nThe first thing you'll probably want to know is whether or not the the user is already authenticated. To check this you can use the `isAuthenticated` method of the current user:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var user = Ionic.User.current();\\n\\nif (user.isAuthenticated()) {\\n  // the user is already signed in\\n} else {\\n  // we need to show a login or sign up form\\n}\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nYou may also want provide a manual logout button in your app in case you remember users by default. Because there can only be a single authenticated user at any given time, we logout users using the `Ionic.Auth.logout` method:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Ionic.Auth.logout();\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]","excerpt":"Learn how the User system works","slug":"user-overview","type":"basic","title":"Overview"}

Overview

Learn how the User system works

A fundamental component of most applications is the concept of a user account. This is almost always accompanied by some form of registration, and ultimately an authentication process. That's why we have built these components for use in your app, we call this Ionic Auth and Ionic Users interchangeably, but they are slightly distinct concepts that work in tandem. Let's discuss the concepts of each of these components individually and then talk about how they are most useful when combined. * [User Registration](#user-registration) * [Authentication](#authentication) * [User Data](#user-data) * [Bringing it all together](#bringing-it-all-together) * [Useful Methods](#useful-methods) [block:api-header] { "type": "basic", "title": "User Registration" } [/block] Most of you should already be familiar with the user registration process, after all, you went through the process signing up at [apps.ionic.io](https://apps.ionic.io). A registration process typically asks you to fill out a few simple details like your name, e-mail, and potentially a username, which is then used to create a *unique* account for the user who filled out the details. The application can then store those details for later use with that account. This is also called a *signup* or *account creation*. Sometimes the details given conflict with an existing account, and the user will need to provide different information (perhaps the user actually already had an account!). No matter the name or process used to ask for information, the end result is the same in Ionic.Auth, a **User** is created and assigned a unique id. Simple, right? [block:api-header] { "type": "basic", "title": "Authentication" } [/block] Typically an application has some form of authentication process (you may be more familiar with the term *login* or *sign up*) when the application starts. There are many different ways to do this, but typically you'll see a username and password prompt, or maybe a button that says *Login with Twitter*. These two examples actually behave very differently in most cases as the former usually authentications with the current application, while the latter authenticates with a 3rd party. The process you use to authenticate does not tend to change the purpose of authenticating, which is to verify a *user* is who he or she says they are. The basic idea is that only the person attempting to authenticate should know the specific details (email/password for example) of the account they want to use. [block:api-header] { "type": "basic", "title": "User Data" } [/block] There are millions of different reasons to want/need user data in your app, but we will work off the basic idea that your app needs to store user preferences. Let's say your app has a light and a dark theme that you want your users to be able to select between at will. Pretend for a moment that you have a limited concept of a user, which is essentially *whoever happens to be using this device at this time*. You could easily store the theme preference in localStorage and would easily be able to read the preference each time the application opens, but what happens when the device is shared between multiple people (perhaps this is an iPad used by a family). Assuming each person has their own preference for which theme to use, it's likely that each time they open your app they will need to reset the theme preference. What about if they buy another device, or want to use the app on their phones? Now they have to manage their preferences between multiple devices... With such a basic example I'm sure you could think of a way to get around this, but instead let's talk about what would happen if each *person* had an account with your app. If you stored the preference with the account, you can now share the same preference across multiple devices, and each user would only need to enter their preference one time! So, that's just one basic example, but the main idea here is that each user can have their own set of data that your app can read from. This doesn't need to be just user preferences, you could store contact information, birthdates, data for interacting with other systems, or maybe something more complex like user reminders. [block:api-header] { "type": "basic", "title": "Bringing it all together" } [/block] So we've talked about each of the different concepts, now let's talk about how we utilize each of these steps using `Ionic.Auth` and `Ionic.User` [block:callout] { "type": "info", "body": "For brevity, we will not be covering how to collect data from the user in the signup and login steps, but will instead just focus on using the pre-collected data with the platform web client." } [/block] The first thing we want someone to do in our app is to signup. We'll do this with basic authentication. Basic authentication uses an e-mail and password to login so that's what we need to collect first: [block:code] { "codes": [ { "code": "var details = {\n 'email': 'example@example.com',\n 'password': 'secretpassword'\n};", "language": "javascript" } ] } [/block] Now that we've collected some details we can attempt to signup: [block:code] { "codes": [ { "code": "Ionic.Auth.signup(details).then(signupSuccess, signupFailure);", "language": "javascript" } ] } [/block] `signupSuccess` and `signupFailure` are success and failure callbacks respectively. You can learn more about how to handle errors [here](doc:user-authentication#section-handling-registration-errors), but we'll assume that the signup was successful for now. Now we have a user account created with the details we collected previously. The user will no longer need to signup again. However, now we need the user to login: [block:code] { "codes": [ { "code": "var options = { 'remember': true };\nIonic.Auth.login('basic', options, details).then(authSuccess, authFailure);", "language": "javascript" } ] } [/block] Let's talk about those two lines a bit more: The first line is just an object that contains options for the login. Currently, the only key available is `remember`, which is a boolean value to determine if the user should remain logged after they close the app. The second line has a bit more going on, the first thing to note is that we are calling `Ionic.Auth.login`. This is the method you will always use to login. The first parameter is the type of authentication to use. In our case we are using `basic` authentication. There are several other types but we will not be covering them here. Check out the [Authentication](doc:user-authentication) page for more information. The 2nd and 3rd parameters just use the previously defined data, and finally we use `authSuccess` and `authFailure` which are callbacks for success and failure. You'll want to replace those with your own methods. Check out our [basic example](doc:user-authentication#section-basic-example) for a more complete example. Now we have successfully authenticated the user. You can now interact with the current user as normal. See the [Usage](doc:user-usage) page for more details on what you can do with a user, but for now we'll just talk about some key methods you'll want to take advantage of... [block:api-header] { "type": "basic", "title": "Useful Methods" } [/block] Alright, we've shown you how to register and login, and the [user usage](doc:user-usage) page discusses the user methods, but let's cover a typical usage you'll want to use in your app. The first thing you'll probably want to know is whether or not the the user is already authenticated. To check this you can use the `isAuthenticated` method of the current user: [block:code] { "codes": [ { "code": "var user = Ionic.User.current();\n\nif (user.isAuthenticated()) {\n // the user is already signed in\n} else {\n // we need to show a login or sign up form\n}", "language": "javascript" } ] } [/block] You may also want provide a manual logout button in your app in case you remember users by default. Because there can only be a single authenticated user at any given time, we logout users using the `Ionic.Auth.logout` method: [block:code] { "codes": [ { "code": "Ionic.Auth.logout();", "language": "javascript" } ] } [/block]