Qiscus Chat SDK provides a simple way to let applications publish and listen to some real-time events. You can publish typing, read, user status, custom event so that you can handle freely in the event handler. This lets you inform users that another participant is actively engaged in communicating with them.
Qiscus Chat SDK is using EventBus for broadcasting event to the entire applications. You can learn more about EventBus on this website. What you need to do is register the object which will receive event from EventBus. You can call it like this:
EventBus.getDefault().register(this);
Once you don't need to listen to the event anymore, you have to unregister the receiver by calling this method:
EventBus.getDefault().unregister(this);
This is an example on how to register an activity to receive event from EventBus:
public class MyActivity extends AppCompatActivity {
@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_my);
}
@Override
protected void onResume() {
super.onResume();
EventBus.getDefault().register(this); // register to EventBus
}
@Override
protected void onPause() {
super.onPause();
EventBus.getDefault().unregister(this); // unregister from EventBus
}
}
Info
After you register the receiver, now you can subscribe to a specific event you need to know. What you need to do is you have to create a method with org.greenrobot.eventbus.Subscribe annotation. The method's name is up to you, but the parameter in your method must be equal with the event class which you want to listen to.
Receiving Message
Messages can be received through a OnReceiveComment event. This event is triggered whenever users send a message. you can implement this event, for example:
@Subscribe
public void onReceiveComment(QiscusCommentReceivedEvent event) {
event.getQiscusComment(); // to get the comment
}
You can set the method name freely, for example:
@Subscribe
public void onGotQiscusMessage(QiscusCommentReceivedEvent event) {
event.getQiscusComment(); // to get the comment
}
The implementation of activity class will be like this:
public class MyActivity extends AppCompatActivity {
@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_my);
}
@Override
protected void onResume() {
super.onResume();
EventBus.getDefault().register(this); // register to EventBus
}
@Override
protected void onPause() {
super.onPause();
EventBus.getDefault().unregister(this); // unregister from EventBus
}
@Subscribe
public void onReceiveComment(QiscusCommentReceivedEvent event) {
event.getQiscusComment(); // to get the comment
}
}
Warning
QiscusCommentReceivedEvent does not guarantee the event only published once per unique comment. There will be the same QiscusCommentReceivedEvent published, so you need to handle it.
Typing Status
You can have a typing status by publishing the typing event. You need to pass roomId and typing status. Set true to indicate the typing event is active, set false to indicate the event is inactive, you can use the code below:
QiscusPusherApi.getInstance().setUserTyping(roomId, typing);
A bit different from listening onReceiveComment event, listening to user typing is not automatically started. You need to listen to an event on specific roomId. We make it like that due to performance reason, because, listening event in too many Chat Rooms at the same time is not good.
We highly recommend you to just listen to event in the active room. To listen to an event in the active Chat Room, you can call method from QiscusPusherApi class. You need to pass qiscusChatRoom object to define which room you need to listen, for example:
QiscusPusherApi.getInstance().listenRoom(qiscusChatRoom);
Once you don't need to listen this event, you have to unlisten by calling this method unlistenRoom, for example:
QiscusPusherApi.getInstance().unListenRoom(qiscusChatRoom);
After you call listenroom method from QiscusPusherApi, now you can subscribe to Chat Room event class which is com.qiscus.sdk.event.QiscusChatRoomEvent as listen on onReceiveComment, for example:
@Subscribe
public void onReceiveRoomEvent(QiscusChatRoomEvent roomEvent) {
if (roomEvent.getEvent() == QiscusChatRoomEvent.Event.TYPING) {
roomEvent.getRoomId(); // this is the room id
roomEvent.getUser(); // this is the qiscus user id
roomEvent.isTyping(); // true if the user is typing
}
}
Getting Participant Online Status
This section suits when you want to know whether the participant is online or not (last active). This case is only for 1-on-1 Chat Room. You can get participant's online status by passing related userId, for example:
QiscusPusherApi.getInstance().listenUserStatus("userId");
After that, you can create method that subscribes to event with com.qiscus.sdk.event.QiscusUserStatusEvent class, for example:
@Subscribe
public void onUserStatusChanged(QiscusUserStatusEvent event) {
event.getUser(); // this is the qiscus user id
event.isOnline(); // true if user is online
event.getLastActive(); // Date of last active user
}
Once you don't need this event anymore, you need to unlisten by calling this method:
QiscusPusherApi.getInstance().unListenUserStatus("userId");
Customizing Real-Time Event
You can publish and listen to any events such as when participant is listening to music, writing document, and many other cases that you need to tell to other participants in a Chat Room.
First, you need to pass roomId with related ChatRoom you want to set, and the structured data to define what event that you want to send. Below is the example of structured data of writing document event:
{
"sender": "John Doe",
"event": "writing document...",
"active": "true"
}
After that, you can send event using this following method *setEvent: *
QiscusPusherApi.getInstance().setEvent(long roomId, JSONObject data)
If you need to stop telling other participants that event is ended, you can send a flag to be false within your structured data, for example:
{
"sender": "John Doe",
"event": "writing document...",
"active": "false"
}
After sending an event, then you need to listen to the event with related roomId, for example:
QiscusPusherApi.getInstance().listenEvent(roomId);
To retrieve event data, you can use EventBus by implementing @Subscribe annotation, for example:
@Subscribe
public void onReceiveRoomEvent(QiscusChatRoomEvent roomEvent) {
switch (roomEvent.getEvent()) {
case CUSTOM:
//here, you can listen custom event
roomEvent.getRoomId(); // this is the room id
roomEvent.getUser(); // this is the sender's qiscus user id
roomEvent.getEventData(); //event data (JSON)
break;
}
}
Connection to Qiscus Server
You can have a control in your App when you are connected or disconnected from Qiscus Server. You need to subscribe using EventBus, for example:
@Subscribe
public void onConnection(QiscusMqttStatusEvent mqttStatusEvent){
switch (mqttStatusEvent) {
case CONNECTED:
// you can do anyting
break;
case DISCONNECTED:
// you can do anyting
break;
..
}
}
Message Status Change
After you listen some of events in a ChatRoom, you can receive the real-time message status which is defined by the event, such as delivered and read , for example:
@Subscribe
public void onReceiveRoomEvent(QiscusChatRoomEvent roomEvent) {
switch (roomEvent.getEvent()) {
case DELIVERED:
roomEvent.getRoomId(); // this is the room id
roomEvent.getUser(); // this is the qiscus user id
roomEvent.getCommentId(); // the comment id was delivered
break;
case READ:
roomEvent.getRoomId(); // this is the room id
roomEvent.getUser(); // this is the qiscus user id
roomEvent.getCommentId(); // the comment id was read
break;
}
}
This is the complete version of using Qiscus Event Handler:
public class MyActivity extends AppCompatActivity {
@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_my);
// listen room event
QiscusPusherApi.getInstance().listenRoom(qiscusChatRoom);
// listen user status
QiscusPusherApi.getInstance().listenUserStatus("userId");
}
@Override
protected void onResume() {
super.onResume();
EventBus.getDefault().register(this); // register to EventBus
}
@Override
protected void onPause() {
super.onPause();
EventBus.getDefault().unregister(this); // unregister from EventBus
}
@Subscribe
public void onReceiveComment(QiscusCommentReceivedEvent event) {
event.getQiscusComment(); // to get the comment
}
@Subscribe
public void onReceiveRoomEvent(QiscusChatRoomEvent roomEvent) {
switch (roomEvent.getEvent()) {
case TYPING:
roomEvent.getRoomId(); // this is the room id
roomEvent.getUser(); // this is the qiscus user id
roomEvent.isTyping(); // true if the user is typing
break;
case DELIVERED:
roomEvent.getRoomId(); // this is the room id
roomEvent.getUser(); // this is the qiscus user id
roomEvent.getCommentId(); // the comment id was delivered
break;
case READ:
roomEvent.getRoomId(); // this is the room id
roomEvent.getUser(); // this is the qiscus user id
roomEvent.getCommentId(); // the comment id was read
break;
case CUSTOM:
//here, you can listen custom event
roomEvent.getRoomId(); // this is the room id
roomEvent.getUser(); // this is the qiscus user id
roomEvent.getEventData(); //event data (JSON)
break;
}
}
@Subscribe
public void onUserStatusChanged(QiscusUserStatusEvent event) {
event.getUser(); // this is the qiscus user id
event.isOnline(); // true if user is online
event.getLastActive(); // Date of last active user
}
@Override
protected void onDestroy() {
super.onDestroy();
// stop listening room event
QiscusPusherApi.getInstance().unListenRoom(qiscusChatRoom);
// stop listening user status
QiscusPusherApi.getInstance().unListenUserStatus("qiscus_user_id");
}
}
