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
  • 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 LYRIdentity class and are returned by APIs that involve identity information (such as the sender of a message, or the currently authenticated user). Instances of LYRIdentity contain a number of properties reflecting the profile information for that user. Currently, the SDK instantiates LYRIdentity 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 userID to create a queryable `LYRIdentity` object that receives updates via Platform API
NSError *error;
BOOL success = [layerClient followUserIDs:[NSSet setWithObject:@"userID"] error:&error];

// Unfollows a userID to stop receiving identity mutation updates
NSError *error;
BOOL success = [layerClient unfollowUserIDs:[NSSet setWithObject:@"userID"] error:&error];

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`
LYRQuery *query = [LYRQuery queryWithQueryableClass:[LYRIdentity class]];
query.predicate = [LYRPredicate predicateWithProperty:@"displayName" predicateOperator:LYRPredicateOperatorIsEqualTo value:@"randomName"];

// Queries for all identities with display name beginning with `rando`
LYRQuery *query = [LYRQuery queryWithQueryableClass:[LYRIdentity class]];
query.predicate = [LYRPredicate predicateWithProperty:@"displayName" predicateOperator:LYRPredicateOperatorLike value:@"rando%"];

// Queries for all identities that start with `random`, any character, and end with `ame`
LYRQuery *query = [LYRQuery queryWithQueryableClass:[LYRIdentity class]];
query.predicate = [LYRPredicate predicateWithProperty:@"displayName" predicateOperator:LYRPredicateOperatorLike value:@"random_ame"];

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 feature has the following 2 concepts.

  • LYRIdentity.presenceStatus: An enum value reporting on the user’s last known status.
  • LYRIdentity.lastSeenAt: An NSDate instance indicating when the user was last known to be online.

Viewing PresenceStatus

The presenceStatus property can have one of the following values:

  • LYRIdentityPresenceStatusOffline: The user is currently offline. For the currently authenticated user, this indicates that the user has never set their presence status.
  • LYRIdentityPresenceStatusAvailable: The user is currently online
  • LYRIdentityPresenceStatusBusy: The user’s status has been set to “busy”
  • LYRIdentityPresenceStatusAway: The user’s status has been set to “away”
  • LYRIdentityPresenceStatusInvisible: In order to make the currently authenticated user appear “offline” for others, you should change the presence status to “invisible”.

Presence status is retrievable by accessing the LYRIdentity's accessor:

LYRIdentityPresenceStatus status = identity.presenceStatus;

Viewing the lastSeenAt

Last seen at information is retrievable by accessing the LYRIdentity's accessor:

NSDate *lastSeenAt = identity.lastSeenAt;

Updating the presenceStatus

The LYRClient instance provides a setPresenceStatus:error: method that allows changing the currently authenticated user’s presence status:

NSError &error;
BOOL success = [layerClient setPresenceStatus:LYRIdentityPresenceStatusAvailable error:&error];
if (!success) {
    // handle error here
}

Updating the lastSeenAt

The lastSeenAt accessor’s value is a read-only value assigned by the Layer’s messaging platform (based on when the user’s client was connected), there’s no ability to override this behavior.

Authentication Conversations