Identities

Identities represent users within your application; they are used

  1. To identify a user to Layer’s APIs
  2. To provide your application with information to help render each user

Each Identity should contain:

  • A User ID: Allows you to map the Identity to a user in your own User Management system
  • An Identity ID: Allows you to identify the user to Layer APIs
  • A Display Name: Helps you render the user, for example, putting their name next to a Message they sent
  • An Avatar URL: Helps you render the user, for example, putting their image next to a Message they sent

Identity properties can be setup while generating Identity Tokens within the authentication handshake or via Server API.

Using identities

Identities are modeled by the Identity class and are returned by APIs that involve identity information (such as the sender of a message, or the currently authenticated user). Instances of Identity contain a number of properties reflecting the profile information for that user. Currently, the SDK instantiates Identity objects as needed; there is no need for developers to create their own instances.

Setting identity fields

You can include some identity fields in your identity token upon authentication.

Currently it is not possible to update identity fields from the Layer SDK.

To update identity fields, please use the Server API.

Following

Users can be followed in order to receive updates when changes are made to their Identity. Any participant in a Conversation with your user is already implicitly followed and cannot be explicitly unfollowed. Other users can be explicitly followed or unfollowed via this API. This is useful for presenting a searchable list of identities a user can begin a new conversation with, without relying on an external user management system.

// Follow a user ID to create a queryable `Identity` object that receives updates via the Platform API
layerClient.follow("userID");

// This can also be used with `Identity` objects
Identity identity = ...;
layerClient.follow(identity);

// Unfollows a user to stop receiving identity mutation updates
layerClient.unFollow(identity);

Querying

Identities can be accessed by Querying, providing a simple way to load and page through Identities. Only Identities of users followed by your user will be loaded. Note that un-followed users will be loaded if they were followed at any point after the initial authentication. In this case the Identity will have its followed flag set to false.

// Queries for all identities with display name `randomName`
Query<Identity> query = Query.builder(Identity.class)
        .predicate(new Predicate(Identity.Property.DISPLAY_NAME, Predicate.Operator.EQUAL_TO, "randomName"))
        .build();

// Queries for all identities with display name beginning with `rando`
Query<Identity> query = Query.builder(Identity.class)
        .predicate(new Predicate(Identity.Property.DISPLAY_NAME, Predicate.Operator.LIKE, "rando%"))
        .build();

// Queries for all identities that start with `random`, any character, and end with `ame`
Query<Identity> query = Query.builder(Identity.class)
        .predicate(new Predicate(Identity.Property.DISPLAY_NAME, Predicate.Operator.LIKE, "random_ame"))
        .build();

Presence

Presence allows a user to see that other users are online, and either available, busy, away or offline. To see presence, one must Follow a user, the SDK will expose their presence information and presence updates to you.

Presence is only available in WebSDK 3.2, iOS 0.26.0 and Android SDK 0.23.13

Authentication Conversations