When a user authenticates with the Layer service, they are effectively "logged in". A copy of all their conversations and messages will dowloaded and stored in a local database, and all sent messages will be attributed to that user.
When handling user management, keep the following in mind:
- Users are tracked by a User ID that you supply to Layer. As long as they are unique, these identifiers can be UDIDs, Facebook IDs, handles or usernames, email addresses, etc.
- Only one user can be authenticated on any device at a time.
- The app must be connected to the Layer service before a user can be authenticated. If the app is not connected to Layer during the authenticate call, a new connection will automatically be established.
- The same user can be authenticated on multiple devices. No matter which device(s) a user is authenticated on, he or she will receive notifications and updates to conversations / messages.
- You must de-authenticate before authenticating another user. If you app supports multiple users, take this into account when logging out a user. Make sure you wait for the appropriate callback before allowing another user to authenticate.
- When a user de-authenticates, all locally stored conversations and messages are deleted. They will be synced again the next time the user authenticates.
- There are three ways a user can de-authenticate:
- You explicitly call de-authenticate
- The Identity Token from your authentication service expires
- The app is deleted from the device (data is cleared)
- You must be online in order to de-authenticate a user, so that the local message queue gets sent to the Layer server.
- Before you go live with Layer, you must create your own authentication web service.
The authentication process ensures that you have complete control over user registration and login. It also guarantees, through the identity token generated by your web service, that only authorized users can communicate through Layer.
The authentication flow:
- The client connects to the Layer service
- The client requests authentication
- Layer generates a nonce and returns it to the client
- The client receives the nonce, and passes it to your authentication web service
- Your authentication web service returns an Identity Token to the client
- Client sends the Identity Token to the Layer service
- Client receives a callback indicating authentication success or failure