How to model an app user in ApiOmat
Most of the time when creating a new app, we are confronted with the central question: How to model a user of my app? This article shows the best practices in ApiOmat, and gives some examples about the usage of the user model.
In ApiOmat, existing data models or classes are encapsulated in modules. One module is automatically contained in every app: The Basics module. If you are searching for a representation of a user, you will find it right in this module: The User class. A user represents one installation of your app; he therefore has to be unique per device. You find examples below Creation and loading of a new user. This unique relation is necessary to ensure a proper authentication of requests against ApiOmat. If the same user would be used on more than one device, no clear separation of data would be possible. If no user would be used at all, only free accessible data could be retrieved. Additionally, some other modules like Push or Facebook are based on the concept of unique users per device and would not work when sharing users.
User insights
A user contains some basic attributes, which are primarily used for authentication:
-
userName - Unique user name or email address (obligatory)
-
password - Password of the user (obligatory)
-
firstName - First name of the user
-
lastName - Last name of the user
-
dateOfBirth - User's date of birth
It can be seen that every user has to have at least a userName and password.
A deeper look into the class shows an attribute named dynamicAttributes; this map is not writable and only for internal use. It is used to store additional user attributes in a dynamic way, which are injected by other modules. For example, if you add the Push Module to your app, your user will automatically be enriched with some more attributes seen in the SDK to store the Push tokens.
Creation and loading of a new user
If you select the user class in the left menu and switch to the SDK afterwards, you will see example code for user creation in all SDK languages (Javascript, iOS,...). The following code will automatically create a new user if it did not exist before:
// Create a new member/user of your app User myUser=new User();myUser.setUserName("johnDoe");myUser.setPassword("1,618");// configure datastore with user credentials Datastore.configure( myUser );// Try to load user or create new one if not exists myUser.loadMeAsync(new AOMEmptyCallback() { @Override public void isDone(ApiomatRequestException exception) { if(exception!=null) { myUser.saveAsync(null); } }} );
The workflow in creating a user is always the same:
-
Create a user
-
Call Datastore.configure(), which will set the user's credentials for the following requests to ApiOmat
-
Load an existing user (loadMe())
-
Or: save the user(save())
It is very important to call Datastore.configure() before the first request. Otherwise the communication layer will not have the necessary information to communicate with ApiOmat.
Reset password
While all other attributes of a user can be set using the setter methods, special methods are used to reset password:
-
resetPassword() – Sends a generated password to the user via email. This is useful if he forgot the old password. It is necessary to use a valid email address as userName to make this method work!
-
changePassword – Changes the password to a new value. The Datastore gets automatically reconfigured with the new credentials afterwards.
Extending user class
In some cases, the existing attributes in the user class will not suffice the needs of you app. Then, you can simply build you own class in Class Editor (e.g. JiraUser in the image), and inherit from the user class. Your own class will inherit all attributes and behavior from the standard user class and can be used for authentication, too. The example code in SDK will show you how:
// Create a new member/user of your app JiraUser myUser=new JiraUser();myUser.setUserName("johnDoe");myUser.setPassword("1,618");// configure datastore with user credentialsDatastore.configure( myUser );... Roles and Security
An authentication with a user permits access to all data with the User and Guest rights. An extension to this rights management is also possible: You can find additional documentation for security for complex cases here.
The default access rules of the basics.User class allow all users to read the data of other users. You can either create a subclass and modify the access rules, or change the configuration of the module "Basics" accordingly (see Basic Module).
Billing
Based on the usage of the User class the number of active users is calculated, which is one part used for billing purposes. An active user is a user who made requests against ApiOmat or received push messages in the last 30 days. To ensure a proper calculation, the implementation of the user in your app must follow the above advises (one app installation = one unique user). Misuse or sharing of users is detected.