Presence and Timeline Events
Okay, now that you’ve laid a solid foundation for sending and receiving messages in your app, it’s time to step up the game and enrich your app with a lot more features Mitter.io has to offer.
User presence is a vital ingredient of any solid messaging platform. Mitter.io is no exception. The SDK gives you multiple ways to update your user’s presence without the hassle.
Presence, as the name suggests, is the current availability of a user. It is usually a single word which tells whether the user is currently available to chat or is not available at the moment.
The Mitter Android SDK ships with a couple of default presence types which you can use to get started:
- Online
- Away
- Sleeping
- Missing
- Offline
Each of these presence types has a
timeToLive field which indicates the time in seconds up to which a presence is valid. After the time has elapsed, the user presence automatically shifts to the next presence in line (if any).The SDK allows you to update the current user’s presence in two ways:
- Update the presence manually
- Tell the SDK to keep updating the presence automatically
Regardless of which approach you choose, you need a
Presence object, to begin with. Therefore, let’s build one:Kotlin
Java
val presence = PresenceBuilder()
.startWith(StandardUserPresenceTypes.online(15))
.then(StandardUserPresenceTypes.away(30))
.then(StandardUserPresenceTypes.sleeping(60))
.then(StandardUserPresenceTypes.offline())
.build()
Presence presence = new PresenceBuilder()
.startWith(StandardUserPresenceTypes.INSTANCE.online(15))
.then(StandardUserPresenceTypes.INSTANCE.away(30))
.then(StandardUserPresenceTypes.INSTANCE.sleeping(60))
.then(StandardUserPresenceTypes.INSTANCE.offline(0))
.build();
Here, we’re using the handy
PresenceBuilder to build a cascading presence in a fluent manner. In a nutshell, the user’s presence begins with Online then shifts to Away after 15 seconds and so on.Now that you have the
Presence object, you can choose either the manual approach or the automatic one for updating. It’s recommended that you use the automatic approach as it’s less management work for you.Update presence automatically
To start updating the current user’s presence automatically, all you need to do is call the
startAutoUpdateCurrentUserPresence() method on the Users object:Kotlin
Java
users.startAutoUpdateCurrentUserPresence(presence)
users.startAutoUpdateCurrentUserPresence(presence, 5);
What’s happening behind the scenes is that the SDK periodically polls on your behalf to update the current user’s presence as
Online. Once the user exits your app, it stops polling and as a result, the presence starts expiring to the next status as discussed earlier.Note: Here, the second argument value is the polling interval (in secs). Therefore, this example sets polling every 5 seconds.
Update presence manually
If you prefer not to use the automatic approach, the SDK also allows you to update the current user’s presence in a single shot.
To update the current user’s presence you need to call the
setCurrentUserPresence() method on the Users object. Something like this:Kotlin
Java
users.setCurrentUserPresence(
presence,
object : Mitter.OnValueUpdatedCallback {
override fun onSuccess() {
Log.d("Mitter", "Presence updated!")
}
override fun onError(error: ApiError) {
Log.d("Mitter", "User Presence - ApiError: $error")
}
}
)
users.setCurrentUserPresence(
presence,
new Mitter.OnValueUpdatedCallback() {
@Override
public void onSuccess() {
Log.d("Mitter", "Presence updated!");
}
@Override
public void onError(ApiError apiError) {
Log.d("Mitter", "User Presence - ApiError: " + apiError);
}
}
);
Note: This is a one-shot update call. If you don’t make this call periodically, the current user’s presence will shift to the next expiring presence after thetimeToLivehas elapsed, even if your app is open.
Just as you to seamlessly set the current user’s presence, you can easily fetch any user’s presence by calling the
getUserPresence() method on the Users object.Just do the following:
Kotlin
Java
users.getUserPresence(
userId = "debd7e00-1c3e-463c-92d1-dbb0e9e0e4ba",
onValueAvailableCallback = object : Mitter.OnValueAvailableCallback<Presence> {
override fun onValueAvailable(value: Presence) {
Log.d("Mitter", "Presence: ${value.type}")
}
override fun onError(apiError: ApiError) {
Log.d("Mitter", "User Presence - ApiError: $error")
}
}
)
users.getUserPresence(
"debd7e00-1c3e-463c-92d1-dbb0e9e0e4ba",
new Mitter.OnValueAvailableCallback<Presence>() {
@Override
public void onValueAvailable(Presence presence) {
Log.d("Mitter", "Presence: " + presence.getType());
}
@Override
public void onError(ApiError apiError) {
Log.d("Mitter", "User Presence - ApiError: " + apiError);
}
}
);
Unlike setting a presence, the SDK doesn’t currently provide an automatic presence fetching mechanism. This means that you’ll have to poll this call with a short time interval let’s say every 5 seconds, to continuously stay in sync with the other user’s presence.
A good place for doing this would be your chat screen. You can call this method every 5 or 10 seconds on the chat screen for every other participant in the chat except the current user.
That’s all you need to know about handling presence for users. Now, we’ll move on to another interesting topic which is dealing with timeline events.
In the previous sections, we’ve talked a lot about timeline events. You’ve also noticed that you need to add a
SentTime timeline event to every message you sent.You must be wondering, how are the useful exactly and if there are other types of timeline events that you can use. Good news, there are some other timeline events that you can use out the box while always having the ability to spin up a custom event of your own.
Although you can create any custom type of timeline events, Mitter.io provides a set of event types out of the box. Currently, there are 4 standard event types shipped by Mitter.io:
mitter.mtet.SentTime- The time at which the message was sentmitter.mtet.ReceivedTime- The time at which the message was received by the servermitter.mtet.DeliveredTime- The time at which the message was delivered to the usermitter.mtet.ReadTime- The time at which the message was read by the user
While you can any of these standard events from the SDK, the SDK provides convenience methods for the
mitter.mtet.DeliveredTime and mitter.mtet.ReadTime events where you don’t have to set these types explicitly. You’ll see how.Taking an use case of adding a read receipt to a message, this can easily be done by calling the
addReadTimelineEvent() method on the Messaging object. Here’s a quick demo:Kotlin
Java
messaging.addReadTimelineEvent(
channelId = "b8bcb84d-8ad2-4f8a-816e-92772b2b8055",
messageIds = listOf(
"89a3de83-769e-4b62-8fee-b50b197c09b4",
"8e5ea0fe-82e1-4b12-b6ca-5f33d965c0fa"
)
)
messaging.addReadTimelineEvent(
"b8bcb84d-8ad2-4f8a-816e-92772b2b8055",
Arrays.asList(
"89a3de83-769e-4b62-8fee-b50b197c09b4",
"8e5ea0fe-82e1-4b12-b6ca-5f33d965c0fa"
),
null
);
In this example, we’re adding a read timeline event to 2 messages at once without explicitly setting the timeline event type and putting in any timestamp. The SDK does the job for you.
You can, also, attach an optional callback to this method as the last parameter
onValueUpdatedCallback, if you want to be notified after the operation has succeeded.When you grow out the standard use cases, you might want to use the
addTimelineEvent() method to add a timeline event to your messages. This method accepts a TimelineEvent object which you need to construct on your own, fully customised to your needs.Preparing the TimelineEvent object
Before sending out any event, you need to construct a
TimelineEvent object with some required parameters, as follows:Kotlin
Java
val timelineEvent = TimelineEvent(
type = "com.acme.events.GiftCardOpened",
eventTimeMs = System.currentTimeMillis(),
subject = User().setUserId("3764e344-5a53-4c02-8bfa-2b3bc11e7c0e")
)
TimelineEvent timelineEvent = new TimelineEvent(
UUID.randomUUID().toString(),
"",
"com.acme.events.GiftCardOpened",
System.currentTimeMillis(),
new User().setUserId("3764e344-5a53-4c02-8bfa-2b3bc11e7c0e"),
null
);
Here, the
type is the type of the event that you’re sending, eventTimeMs is the timestamp you want to associate with the event and the subject is the user with whom this event should be associated.For example, if you’re sending a read time type of event, the
subject would the receiving user who has read the message.Sending the event
Now that you have the event prepared with your necessary customisations, it’s time to actually send it out for Mitter.io to deliver it to the concerned user(s).
You can do the same by calling the
addTimelineEvent() method and supplying the TimelineEvent object that you created in the previous step. This is how the code looks:Kotlin
Java
messaging.addTimelineEvent(
channelId = "b8bcb84d-8ad2-4f8a-816e-92772b2b8055",
messageIds = listOf(
"89a3de83-769e-4b62-8fee-b50b197c09b4",
"8e5ea0fe-82e1-4b12-b6ca-5f33d965c0fa"
),
timelineEvent = timelineEvent
)
messaging.addTimelineEvent(
"b8bcb84d-8ad2-4f8a-816e-92772b2b8055",
Arrays.asList(
"89a3de83-769e-4b62-8fee-b50b197c09b4",
"8e5ea0fe-82e1-4b12-b6ca-5f33d965c0fa"
),
timelineEvent,
null
);
As you can notice, it’s almost the same as the
addReadTimelineEvent() method with the exception that it accepts a TimelineEvent object without assuming anything on it’s own.This is how you can have full control over what events you want to send out.
This section has dealt with some advanced properties of Mitter.io and how you can leverage them to work the way you want.
In the next section, you’ll learn how to update your user’s profile and adding certain locators that’ll help you find any user in your application.
Last modified 4yr ago