User Experience Guidelines - Android

These practices help users join prepared, see what is happening in the room and fix problems themselves.

Section	Description
Configure Precall Before Joining	Users may enter rooms unprepared due to device or connection issues. A Precall setup lets them configure devices and settings beforehand.
Monitor Key Events for Optimal User Experience	Users can feel lost without real-time updates on room status, events, and errors. Event monitoring and notifications keep them informed and engaged.
Handling Media Devices	Users may want to change their audio or video setup mid-call but struggle to manage device controls. Let them switch devices during the call.
Monitoring Real-Time Participant Statistics	Poor video or audio quality without real-time feedback leaves users frustrated. Real-time stats let them assess connection quality and troubleshoot issues actively.

Configure Precall Before Joining

A Precall step is crucial for ensuring users are set up correctly and have no device issues before joining a room. This step allows users to configure their devices and settings before entering a room, so fewer problems come up once the call begins.

Recommended Practices:

• Request Permissions: Prompt users to grant microphone and camera permissions before entering the room.
• Device Selection: Allow users to select their preferred camera and microphone, giving them control over their setup from the start.
• Entry Preferences: Provide options to join with the microphone and camera either on or off, letting users choose their level of engagement upon entry.
• Camera Preview: Show a live camera preview, allowing users to adjust angles and lighting to ensure they appear clearly and professionally.
• Camera Effects: Allow users to turn on camera effects, such as low-light correction or a color filter, before they join, helping them appear more polished. See Video Effects. A device that can't run the effects sends the video without them.
• Network Check: Run a pre-call test with runPreCallTest() before you call VideoSDK.createRoom(). It checks the camera and microphone and scores the network, so you can warn users about a poor connection before they join. Pass your preview track as videoTrack in PreCallTestOptions, or the test opens the camera itself and ends your preview.

For detailed setup instructions on each of these features, check out our in-depth documentation here.

Monitor Key Events for Optimal User Experience

Listen for room events and tell participants what changed.

Recommended Practices:

• Monitor State Change Events: Listen for state change events, such as onRoomStateChanged and onRecordingStateChanged, and notify users promptly about these transitions. Keeping users informed helps them understand the current state of the room.

• UI Handling on Event Trigger: Update the user interface only in response to specific events. For instance, display that the room is being recorded only when the onRecordingStateChanged event reports RecordingState.RECORDING_STARTED, rather than when the record button is clicked. This ensures users receive accurate and timely updates.

• Notify Participants of Join/Leave Events: Tell users when someone joins or leaves, from onParticipantJoined() and onParticipantLeft() on RoomEventListener.
• Listen for Error Events: Override onError() on RoomEventListener and tell users what went wrong and what to do, such as granting the camera permission. Catch the VideoSDKException that suspend actions throw as well. See Listen for Error Events.

Handling Media Devices

Let participants choose their camera, microphone and speaker. Proper device management within the UI also helps users stay informed about their current settings and troubleshoot issues effectively.

Recommended Practices:

• Allow Device Switching: Provide users with the option to switch between available microphone and camera devices during the call. This flexibility is essential, especially if users want to adjust their setup mid-call. When the camera or microphone is on, changeCam() and changeMic() turn it off and on again on the new device, so onStreamDisabled() and then onStreamEnabled() fire for everyone. Don't announce that pair as the user turning the device off.
• Display Selected Devices: Ensure the UI shows users which microphone and camera devices are currently selected. Clear device labeling in the interface can reduce confusion and help users verify their setup at a glance.

Monitoring Real-Time Participant Statistics

Providing real-time insights into stream quality allows participants to monitor and optimize their connection for the best experience. With detailed metrics on video, audio, and screen sharing, users can assess and troubleshoot quality issues. To display these statistics, you can use the getVideoStats(), getAudioStats(), and getShareStats() methods.

note

getVideoStats() returns a JSONArray with one entry per video stream (one per layer for your own camera when it sends multiple layers), while getAudioStats() and getShareStats() return a single JSONObject. Each returns null when there is no such stream or the stats can't be read, so check the value before you read it. The values refresh at most every 400 ms, so updating the stats dialog about once a second is enough.