Implement co-hosting

This doc will introduce how to implement the co-hosting feature in the live streaming scenario.

Prerequisites

Before you begin, make sure you complete the following:

• Complete SDK integration by referring to Quick Start doc.
• Download the demo that comes with this doc.
• Activate the In-app Chat service.
  

Preview the effect

You can achieve the following effect with the demo provided in this doc:

Homepage	Live stream page	Receive co-hosting request	Start co-hosting

Understand the tech

1. What is roomrequest?

The process of co-hosting implemented based on roomrequest, roomrequest is a protocol or message to manage communication and connections in networks. ZEGOCLOUD packages all roomrequest capabilities into a SDK, providing you with a readily available real-time roomrequest API.

2. How to send & receive roomrequest messages through the ZIM SDK interface

The ZIM SDK provides rich functionality for sending and receiving messages, see Send & Receive messages (roomrequest). And here, you will need to use the customizable roomrequest message: ZIMCommandMessage

Complete demo code for this section can be found at ZIMService.java.

(1) Send RoomRequest (ZIMCommandMessage) in the room by calling sendMessage with the following:

zim.sendMessage(commandMessage, mRoomID, ZIMConversationType.ROOM, config, new ZIMMessageSentCallback() {
    // ...
    @Override
    public void onMessageSent(ZIMMessage message, ZIMError errorInfo) {
        // ...
    }
});

(2) After sending, other users in the room will receive the RoomRequest from the onReceiveRoomMessage callback. You can listen to this callback by following below:

zim.setEventHandler(new ZIMEventHandler() {
    @Override
    public void onReceiveRoomMessage(ZIM zim, ArrayList<ZIMMessage> messageList, String fromRoomID) {
        super.onReceiveRoomMessage(zim, messageList, fromRoomID);

        // ...
    }
});

3. How to customize business RoomRequest

Complete demo code for this section can be found at ZIMService.java and RoomRequest.java.

JSON RoomRequest encoding

Since a simple String itself is difficult to express complex information, RoomRequest can be encapsulated in JSON format, making it more convenient for you to organize the protocol content of the RoomRequest.

Taking the simplest JSON RoomRequest as an example: {"action_type": 10000}, in such a JSON RoomRequest, you can use the action_type field to express different RoomRequest types, such as:

• Sending a request: {"action_type": RoomRequestAction.ACTION_REQUEST}
• Canceling a request: {"action_type": RoomRequestAction.ACTION_CANCEL}
• Accepting a request: {"action_type": RoomRequestAction.ACTION_ACCEPT}
• Rejecting a request: {"action_type": RoomRequestAction.ACTION_REJECT}

In addition, you can also extend other common fields for RoomRequest, such as senderID , receiverID,extended_data :

public class RoomRequest {

    // ...
    public String toString() {
        JSONObject jsonObject = new JSONObject();
        try {
            jsonObject.put("action_type", actionType);
            jsonObject.put("sender_id", sender);
            jsonObject.put("receiver_id", receiver);
            jsonObject.put("extended_data", extendedData);
            jsonObject.put("request_id", requestID);
        } catch (JSONException e) {
            throw new RuntimeException(e);
        }
        return jsonObject.toString();
    }

    // ...
}

public @interface RoomRequestAction {
    int ACTION_REQUEST = 0;
    int ACTION_ACCEPT = 1;
    int ACTION_REJECT = 2;
    int ACTION_CANCEL = 3;
}

JSON RoomRequest decoding

And users who receive RoomRequest can decode the JSON RoomRequest and know and process specific business logic based on the fields in it, such as:

zim.setEventHandler(new ZIMEventHandler() {
    @Override
    public void onReceiveRoomMessage(ZIM zim, ArrayList<ZIMMessage> messageList, String fromRoomID) {
        super.onReceiveRoomMessage(zim, messageList, fromRoomID);

        for (ZIMMessage zimMessage : messageList) {
            if (zimMessage instanceof ZIMCommandMessage) {
                ZIMCommandMessage commandMessage = (ZIMCommandMessage) zimMessage;
                String message = new String(commandMessage.message, StandardCharsets.UTF_8);
                try {
                    JSONObject jsonObject = new JSONObject(message);
                    if (jsonObject.has("action_type")) {
                        jsonObject.put("message_id", String.valueOf(commandMessage.getMessageID()));
                        if (currentUser != null) {
                            onReceiveRoomRequestMessage(jsonObject);
                        }
                    } else {
                        // ...
                    }
                } catch (JSONException e) {
                     // ...
                }
            }
        }
    }
    // ...
)

// ...
private void onReceiveRoomRequestMessage(JSONObject jsonObject) throws JSONException {
    String sender = jsonObject.getString("sender_id");
    String receiver = jsonObject.getString("receiver_id");
    int actionType = jsonObject.getInt("action_type");
    String extendedData = jsonObject.getString("extended_data");
    String messageID = jsonObject.getString("message_id");
    if (currentUser.userID.equals(receiver)) {
        if (actionType == RoomRequestAction.ACTION_REQUEST) {
            // ...
        } else if (actionType == RoomRequestAction.ACTION_ACCEPT) {
            // ...
        } else if (actionType == RoomRequestAction.ACTION_CANCEL) {
            // ...
        } else if (actionType == RoomRequestAction.ACTION_REJECT) {
            // ...
        }
    }
}

Further extending RoomRequest

Based on this pattern, when you need to do any protocol extensions in your business, you only need to extend the extended_data field of the RoomRequest to easily implement new business logic, such as:

• Muting audience: After receiving the corresponding RoomRequest, the UI blocks the user from sending live bullet messages.
• Sending virtual gifts: After receiving the RoomRequest, show the gift special effects.
• Removing audience: After receiving the RoomRequest, prompt the audience that they have been removed and exit the room.

Friendly reminder: After reading the following text and further understanding the implementation of co-hosting RoomRequest, you will be able to easily extend your live streaming business RoomRequest.

sequenceDiagram
    participant Alice
    participant appServer as App Server
    participant server as ZEGOCLOUD Server
    participant sdk as SDK
    participant Bob

    Alice  ->> appServer  : Send co-hosting request
    appServer   ->> appServer  : Process your own business logic
    appServer   ->> server: Alice's co-hosting request
    server ->> sdk  : Alice's co-hosting request
    sdk   ->> Bob   : Alice's co-hosting request


    Note over Alice, Bob: ...

Implementation

Integrate and start to use the ZIM SDK

If you have not used the ZIM SDK before, you can read the following section:

import im.zego.zim.ZIM

ZIMAppConfig appConfig = new ZIMAppConfig();
appConfig.appID = yourAppID;
appConfig.appSign = yourAppSign;
ZIM.create(appConfig, application);

Later on, we will provide you with detailed instructions on how to use the ZIM SDK to develop the call invitation feature.

Manage multiple SDKs more easily

In most cases, you need to use multiple SDKs together. For example, in the live streaming scenario described in this doc, you need to use the zim sdk to implement the co-hosting feature, and then use the zego_express_engine sdk to implement the live streaming feature.

If your app has direct calls to SDKs everywhere, it can make the code difficult to manage and troubleshoot. To make your app code more organized, we recommend the following way to manage these SDKs:

public class ZIMService {

    // ...

    public void initSDK(Application application, long appID, String appSign) {
        zimProxy.create(application, appID, appSign);
        // ...
    }
}

class ZIMProxy {

    private SimpleZIMEventHandler zimEventHandler;

    public void create(Application application, long appID, String appSign) {
        ZIMAppConfig zimAppConfig = new ZIMAppConfig();
        zimAppConfig.appID = appID;
        zimAppConfig.appSign = appSign;
        ZIM.create(zimAppConfig, application);

        zimEventHandler = new SimpleZIMEventHandler();
        if (getZIM() != null) {
            ZIM.getInstance().setEventHandler(zimEventHandler);
        }
    }

}

public class ExpressService {

    // ...
    public void initSDK(Application application, long appID, String appSign, ZegoScenario scenario) {
        ZegoEngineConfig config = new ZegoEngineConfig();
        config.advancedConfig.put("notify_remote_device_unknown_status", "true");
        config.advancedConfig.put("notify_remote_device_init_status", "true");
        ZegoExpressEngine.setEngineConfig(config);
        engineProxy.createEngine(application, appID, appSign, scenario);
        // ...
    }
}

class ExpressEngineProxy {

    private SimpleExpressEventHandler expressEventHandler;

    public void createEngine(Application application, long appID, String appSign, ZegoScenario scenario) {
        ZegoEngineProfile profile = new ZegoEngineProfile();
        profile.appID = appID;
        profile.appSign = appSign;
        profile.scenario = scenario;
        profile.application = application;
        expressEventHandler = new SimpleExpressEventHandler();
        ZegoExpressEngine.createEngine(profile, expressEventHandler);
    }
}

public class ZIMService {
    // ...
    public void connectUser(String userID, String userName, ZIMLoggedInCallback callback) {
        ZIMUserInfo zimUserInfo = new ZIMUserInfo();
        zimUserInfo.userID = userID;
        zimUserInfo.userName = userName;
        zim.login(zimUserInfo, new ZIMLoggedInCallback() {
            @Override
            public void onLoggedIn(ZIMError errorInfo) {
                // ...
            }
        });
    }
}

public class ZEGOSDKManager {
    public ExpressService expressService = new ExpressService();
    public ZIMService zimService = new ZIMService();

    private static final class Holder {
        private static final ZEGOSDKManager INSTANCE = new ZEGOSDKManager();
    }

    public static ZEGOSDKManager getInstance() {
        return Holder.INSTANCE;
    }

    public void initSDK(Application application, long appID, String appSign,ZegoScenario scenario) {
        expressService.initSDK(application, appID, appSign,scenario);
        zimService.initSDK(application, appID, appSign);
    }
}

Later, we will introduce how to add co-hosting feature based on this.

Send & Cancel a co-hosting request

The implementation of sending and canceling co-hosting requests is similar, with only the type of RoomRequest being different. Here, sending will be used as an example to explain the implementation of the demo.

In the Demo, a request co-host button has been placed in the lower right corner of the LivePage as seen from the audience perspective. When the button is clicked, the following actions will be executed.

1. Encode the JSON RoomRequest, where the action_type is defined as RoomRequestAction.ACTION_REQUEST in the demo.

2. Call sendRoomRequest to send the RoomRequest. (sendRoomRequest simplifies the sendMessage interface of ZIM SDK.)

• If the method call is successful: the applying status of the local end (i.e. the audience) will be switched to applying for co-hosting, and the Request Co-host button will switch to Cancel CoHost.
• If the method call fails: an error message will be prompted. In actual app development, you should use a more user-friendly UI to prompt the failure of the co-hosting application.

@Override
protected void afterClick() {
    super.afterClick();
    // ...
    RoomRequestExtendedData extendedData = new RoomRequestExtendedData();
    extendedData.roomRequestType = RoomRequestType.REQUEST_COHOST;
    ZEGOSDKManager.getInstance().zimService.sendRoomRequest(hostUser.userID, jsonObject.toString(),
        new RoomRequestCallback() {
            @Override
            public void onRoomRequestSend(int errorCode, String requestID) {
                if (errorCode == 0) {
                    mRoomRequestID = requestID;
                }
            }
        });
// ... 
}

 public void sendRoomRequest(String receiverID, String extendedData, RoomRequestCallback callback) {
        if (zimProxy.getZIM() == null || currentRoom == null || currentUser == null) {
            return;
        }
        RoomRequest roomRequest = new RoomRequest();
        roomRequest.receiver = receiverID;
        roomRequest.sender = currentUser.userID;
        roomRequest.extendedData = extendedData;
        roomRequest.actionType = RoomRequestAction.ACTION_REQUEST;

        byte[] bytes = roomRequest.toString().getBytes(StandardCharsets.UTF_8);
        ZIMCommandMessage commandMessage = new ZIMCommandMessage(bytes);
        zimProxy.sendMessage(commandMessage, currentRoom.roomID, ZIMConversationType.ROOM, new ZIMMessageSendConfig(),
            new ZIMMessageSentCallback() {
                @Override
                public void onMessageAttached(ZIMMessage message) {

                }

                @Override
                public void onMessageSent(ZIMMessage message, ZIMError errorInfo) {
                    if (errorInfo.code == ZIMErrorCode.SUCCESS) {
                        roomRequest.requestID = String.valueOf(message.getMessageID());
                        roomRequestMap.put(roomRequest.requestID, roomRequest);
                    }
                  // ...
                }
            });
    }

public void updateUI() {
    ZEGOSDKUser localUser = ZEGOSDKManager.getInstance().expressService.getCurrentUser();
    ZIMService zimService = ZEGOSDKManager.getInstance().zimService;
    if (ZEGOLiveStreamingManager.getInstance().isCoHost(localUser.userID)) {
        coHostUI();
    } else if (ZEGOLiveStreamingManager.getInstance().isAudience(localUser.userID)) {
        RoomRequest roomRequest = zimService.getRoomRequestByRequestID(mRoomRequestID);
        if (roomRequest == null) {
            audienceUI();
        } else {
            requestCoHostUI();
        }
    }
}

3. Afterwards, the local end (audience end) will wait for the response from the host.

• If the host rejects the co-host request: the applying status of the local end will be switched to not applying.
• If the host accepts the co-host request: the co-hosting will start (see the co-hosting section for details on starting and ending co-hosting).

Accept & Reject the co-hosting request

1. In the demo, when the host receives a co-hosting request RoomRequest, a red dot will appear on the button in the user list, and the host can choose to accept or reject the user's co-hosting request after clicking on the user list.
2. After the host responds, a RoomRequest of acceptance or rejection will be sent. The related logic of sending RoomRequest will not be further described here.

The relevant code snippet is as follows, and the complete code can be found in RoomRequestButton.java and RoomRequestListAdapter

// ...
@Override
public void onInComingRoomRequestReceived(RoomRequest request) {
    checkRedPoint();
}

private void showRedPoint() {
    redPoint.setVisibility(View.VISIBLE);
}

private void hideRedPoint() {
    redPoint.setVisibility(View.GONE);
}

public void checkRedPoint() {
    ZEGOSDKUser localUser = ZEGOSDKManager.getInstance().expressService.getCurrentUser();
    if (ZEGOLiveStreamingManager.getInstance().isHost(localUser.userID)) {
        List<RoomRequest> myReceivedRoomRequests = ZEGOSDKManager.getInstance().zimService.getMyReceivedRoomRequests();
        boolean showRedPoint = false;
        for (RoomRequest roomRequest : myReceivedRoomRequests) {
            String extendedData = roomRequest.extendedData;
            RoomRequestExtendedData data = RoomRequestExtendedData.parse(extendedData);
            if (data != null && data.roomRequestType == roomRequestType) {
                showRedPoint = true;
                break;
            }
        }
        if (showRedPoint) {
            showRedPoint();
        } else {
            hideRedPoint();
        }
    }
}

@Override
public void onBindViewHolder(@NonNull ViewHolder holder, int position) {
    // ...

    agree.setOnClickListener(v -> {
        ZEGOSDKManager.getInstance().zimService.acceptRoomRequest(roomRequest.requestID, new RoomRequestCallback() {
            @Override
            public void onRoomRequestSend(int errorCode, String requestID) {

            }
        });
    });

    disagree.setOnClickListener(v -> {
        ZEGOSDKManager.getInstance().zimService.rejectRoomRequest(roomRequest.requestID, new RoomRequestCallback() {
            @Override
            public void onRoomRequestSend(int errorCode, String requestID) {

            }
        });
    });
}

Start & End co-hosting

When the audience receives the RoomRequest that the host agrees to co-host, they can become a co-host and start co-host live streaming by calling related methods of zego_express_engine for previewing and publishing streams.

public class LiveStreamingActivity extends AppCompatActivity {
    // ...
    @Override
    public void onOutgoingRoomRequestAccepted(RoomRequest request) {
        RoomRequestExtendedData data = RoomRequestExtendedData.parse(extendedData);
        if (data != null && data.roomRequestType == RoomRequestType.REQUEST_COHOST) {
            ExpressService expressService = ZEGOSDKManager.getInstance().expressService;
            ZEGOSDKUser currentUser = expressService.getCurrentUser();
            if (ZEGOLiveStreamingManager.getInstance().isAudience(currentUser.userID)) {
                List<String> permissions = Arrays.asList(permission.CAMERA, permission.RECORD_AUDIO);
                requestPermissionIfNeeded(permissions, new RequestCallback() {

                    @Override
                    public void onResult(boolean allGranted, @NonNull List<String> grantedList,
                        @NonNull List<String> deniedList) {
                        ZEGOLiveStreamingManager.getInstance().startCoHost();
                    }
                });
            }
        }
    }
    // ...
}

End co-hosting

After the audience ends co-hosting, they need to call relevant methods of zego_express_engine to stop previewing and publishing streams. The complete code can be found in the CoHostButton.java. And the key code is as follows:

public void endCoHost() {
    removeCoHost(ZEGOSDKManager.getInstance().expressService.getCurrentUser());
    ZEGOSDKManager.getInstance().expressService.openMicrophone(false);
    ZEGOSDKManager.getInstance().expressService.openCamera(false);
    ZEGOSDKManager.getInstance().expressService.stopPreview();
    ZEGOSDKManager.getInstance().expressService.stopPublishingStream();
}

Conclusion

Congratulations! Hereby you have completed the development of the co-hosting feature.

If you have any suggestions or comments, feel free to share them with us via Discord. We value your feedback.