Android

Introduction

Real-time messaging provides low latency, high concurrency, and high reliability. It is ideal for scenarios such as live chat and voice chat rooms.

To use the RTM feature in DingRTC, you must first join a meeting.

Related concepts

Session: A real-time messaging session is uniquely identified by a sessionId. A session supports join, leave, and close operations. Before you can send or receive real-time messages, you must create and join a session. In DingRTC, you can create multiple sessions with different sessionId values. These sessions operate independently of each other.

Broadcast message: A message sent to all other members in a session.

Peer-to-peer message: A message sent to a specific user in a session, identified by their UserID.

Integration method

1. Before you join a channel, obtain the DingRtmClient instance from RtcEngine.

   DingRtmClient rtmClient = rtcEngine.getRtmClient();

2. Set a callback listener for the DingRtmClient instance.

   rtmClient.setListener(new DingRtmEventListener() {
       @Override
       public void onRtmServerStateChanged(DingRtmClient.DingRtmServerState state, int errorCode) {
           // Call RTM API methods only after you receive a notification that the state is DingRtmServerState.Available. Otherwise, the calls fail.
       }
   
       @Override
       public void onJoinSessionResult(String sessionId, int result) {
       }
   
       @Override
       public void onLeaveSessionResult(String sessionId, int reason) {
       }
   
       @Override
       public void onCloseSessionResult(String sessionId, int result) {
       }
   
       @Override
       public void onRemovedFromSession(String sessionId, int reason) {
       }
   
       @Override
       public void onSessionCreate(String sessionId) {
       }
   
       @Override
       public void onSessionClose(String sessionId) {
       }
   
       @Override
       public void onSessionRemoteUserJoin(String sessionId, String uid) {
       }
   
       @Override
       public void onSessionRemoteUserLeave(String sessionId, String uid) {
       }
   
       @Override
       public void onMessage(String sessionId, String fromUid, boolean broadcast, byte[] data) {
       }
   });

3. After you join the channel, the session initiator creates and joins a session.

   rtmClient.joinSession(sessionId); // If the session does not exist, calling joinSession creates the session and then joins it.

4. Other members in the channel receive an onSessionCreate event notification and then join the same session.

   rtmClient.joinSession(sessionId); // If the session exists, calling joinSession directly joins it.

5. When you join a session that already has members, or when other members join the session, you receive an onSessionRemoteUserJoin event notification. To send peer-to-peer messages, your application must maintain a list of session members.

   @Override
   public void onSessionRemoteUserJoin(String sessionId, String uid) {
       activity.runOnUiThread(() -> {
           // The addSessionUser method is implemented at the application layer to add a new user to the session.
           addSessionUser(sessionId, uid);
       });
   }

   Similarly, when a user leaves the session, you receive an onSessionRemoteUserLeave event notification. You must update the session member list accordingly.

   @Override
   public void onSessionRemoteUserLeave(String sessionId, String uid) {
       activity.runOnUiThread(() -> {
           // The removeSessionUser method is implemented at the application layer to remove a user from the session.
           removeSessionUser(sessionId, uid);
       });
   }

6. The SDK supports sending and receiving UTF-8 encoded strings and binary data. On Android, messages are passed as a byte array parameter. To send a broadcast message:

   String msg = "test123";
   byte[] byteMsg = msg.getBytes(StandardCharsets.UTF_8);
   rtmClient.broadcastData(sessionId, byteMsg);

   To send a peer-to-peer message:

   String msg = "test123";
   byte[] byteMsg = msg.getBytes(StandardCharsets.UTF_8);
   rtmClient.sendData(sessionId, uid, byteMsg);

   To receive a message:

   @Override
   public void onMessage(String sessionId, String fromUid, boolean broadcast, byte[] data) {
       activity.runOnUiThread(() -> {
           // This assumes the sender sent the message in string format.
           String msg = new String(data, StandardCharsets.UTF_8); 
           Log.d(TAG, "Receive rtm msg, session: " + sessionId 
                   + ", from: " + fromUid + ", msg: " + msg);
       });
   }

7. If you no longer need the RTM feature, leave the session.

   rtmClient.leaveSession(sessionId);

   After you leave a session, you will no longer receive broadcast messages from other members in that session, and they will be unable to send peer-to-peer messages to you.

8. If a session is no longer needed, close it.

   rtmClient.closeSession(sessionId);

   After you close a session, all members, including you, receive an onSessionClose event notification, and the session becomes inactive.

Notes

1. Obtain the DingRtmClient instance and set the listener before you call joinChannel. Otherwise, you might miss some RTM messages.

2. When you leave the channel, the SDK clears all session information, and the RTM feature becomes unavailable.

3. If a remote user calls leaveChannel without first calling leaveSession, you might not receive the onSessionRemoteUserLeave event notification for that user. In this case, when you receive the onRemoteUserOffLineNotify event for that user, your application must remove the user from all session member lists.