Does ZEGO SDK support a fast reconnection for temporary disconnection?

The ZEGO SDK does support this feature.

A fast reconnection for temporary disconnection refers to a mechanism to ensure the users can be quickly reconnected to a room or recover a stream publishing/playing operation after a temporary disconnection occurred due to some exceptions.

This document introduces the handling logic of the SDK when reconnecting to a room, recovering a stream publishing/playing operation, and the methods to handle unexpected disconnections.

1 Handling logic of reconnection

1.1 Reconnect to a room

After logging in to a room, the SDK automatically tries to reconnect when you are disconnected from the room due to network errors.

To receive the updates on the current user's room connection status in real time and handle the event callbacks related to room status, you can listen for the onRoomStateUpdate callback.

For other users in the room, to receive updates on the status of specified users in the room, call the onRoomUserUpdate method. (Remember to set the isUserNotify property of the room configuration parameter config to true when you log in to a room in advance.)

Callback for the room connection status

The following diagram illustrates the callback for updates on the room connection status:

Among the diagram:

• T0 = 0s: The ClientA's SDK receives the loginRoom calling request.
• T1 ≈ T0 + 120ms: Generally, 120 milliseconds after the loginRoom method is called, the client can join in to a room. And in the process of joining the room, the ClientA receives the onRoomStateUpdate(roomID, ZegoRoomStateConnecting, 0, extendedData) and the onRoomStateUpdate(roomID, ZegoRoomStateConnected, 0, extendedData) callbacks, which notifies that it is connecting to the room and room is connected successfully respectively.
• T2 ≈ T1 + 100ms: Due to network transmission delays, the ClientB receives the onRoomUserUpdate(roomID, ZegoUpdateTypeAdd, userList) callback about 100ms later and is notified that the ClientA has joined the room.
• T3: At a certain point in time, the ClientA's uplink network deteriorates due to network disconnection. The SDK tries to re-join the room, and the ClientA receives the onRoomStateUpdate(roomID, ZegoRoomStateConnecting, 0, extendedData) callback and is notified that the reconnection attempt is ongoing.
• T4 ≈ T3 + 90S: The ClientB receives the onRoomUserUpdate(roomID, ZegoUpdateTypeDelete, userList) callback and is notified that the ClientA is disconnected/offline.
• T5 = T3 + time (less than 20 minutes): The ClientA gets reconnected within the default reconnection duration. The ClientA receives the callback onRoomStateUpdate(roomID, ZegoRoomStateConnected, 0, extendedData) and is notified that the reconnection attempt is successful.
• T6 ≈ T5 + 100ms: Due to network transmission delays, the ClientB receives the onRoomUserUpdate(roomID, ZegoUpdateTypeAdd, userList) callback about 100ms later and is notified that the ClientA has reconnected successfully.
• T7 = T3 + 20min: If the ClientA fails to re-join the room for over 20 minutes, the SDK will not try to reconnect again. The ClientA receives the onRoomStateUpdate(roomID, ZegoRoomStateDisconnected, 0, extendedData) callback and is notified the it is disconnected.

1.2 Recover a stream publishing operation

During a stream publishing process, the SDK automatically tries to recover the operation when the streaming publishing failed due to network errors.

If all nodes have been tried, but the stream publishing still failed, the SDK sends out notification through the callback onPublisherStateUpdate. In this callback, when the state is ZegoPublisherStateNoPublish and the errorCode is not 0, indicates the SDK's recovery attempt has failed. The error can be determined based on the value of the errorCode, for details, see Error codes.

At this point, we recommend waiting a few seconds (3-5 seconds) to start publishing the stream again, rather than getting stuck in an infinite loop by trying again and again.

Callback for stream publishing status

1.3 Recover a stream playing operation

During a stream playing process, the SDK automatically tries to recover the operation when the streaming playing failed due to network errors.

If all nodes have been tried, but the stream playing still failed, the SDK sends out notification through the callback onPlayerStateUpdate. In this callback, when the state is ZegoPlayerStateNoPlay and the errorCode is not 0, indicates the SDK's recovery attempt has failed. The error can be determined based on the value of the errorCode, for details, see Error codes.

At this point, we recommend waiting a few seconds (3-5 seconds) to start playing the stream again, rather than getting stuck in an infinite loop by trying again and again.

Callback for stream playing status

1.4 Set the reconnection duration

• If the user got disconnected due to network errors, the SDK tries to reconnect for 20 minutes by default. If the reconnection fails after 20 minutes, it won't try again.
  • To set the reconnection duration for room reconnection, call the setEngineConfig method and set the parameter "room_retry_time=xxxx"（unit: second).
  • To set the reconnection duration for stream publishing/playing recovery, call the setEngineConfig method and set the parameter "av_retry_time=xxxx"（unit: second).
• If the process exits unexpectedly, the SDK tries to reconnect for 20 minutes by default. If the reconnection fails after 20 minutes, it won't try again. To modify the default reconnection duration, contact the ZEGO technical support.

2 Handle unexpected disconnections

2.1 SDK side: how to handle when the host end gets disconnected

The SDK detects the network status of the host in real time. When the host is disconnected, it automatically stops the stream publishing. If the network recovers within 300 seconds, the SDK automatically publishes streams again.

When the host is disconnected:

• If the network does not recover after 90 seconds: All audience in the room will be notified that existing streams in the room stop through the callback onRoomStreamUpdate, and audience in the room can call the stopPlayingStream method to stop playing the streams.
• If the SDK retries to publish the streams successfully: All audience in the room will be notified that new streams are published to the room through the callback onRoomStreamUpdate, and audience in the room can call the startPlayingStream to start playing the streams again.

2.2 Audience side: how to handle when the host end gets disconnected

After the host is disconnected, the audience will fail to play the streams in the room, meanwhile, the SDK will automatically try to recover the stream playing. If the SDK fails to recover the operation, audience will be notified through the callback onPlayerStateUpdate (when the errorCode is not 0, we recommend audience to try playing the stream after a while, for example, 3 seconds).

During the SDK recovery attempt, the audience can do the following accordingly:

• If the host gets reconnected, and the SDK recovered the stream playing successfully, the audience can continue to play streams.
• If the host did't get reconnected for a while: after 90-second disconnection, the audience in the room will be notified that existing streams in the room stop through the callback onRoomStreamUpdate, and audience in the room can call the stopPlayingStream method to stop playing the streams.
• If the host gets reconnected and published new streams to the room: the audience in the room will be notified that new streams are published to the room through the callback onRoomStreamUpdate, and audience in the room can call the startPlayingStream to start playing the streams again.

2.3 Audience side: how to handle when the host end gets crash

When the host end gets crash, and does not restart the live streaming for a while, the audience will be notified that existing streams in the room stop through the callback onRoomStreamUpdate.

For this circumstance, the audience can do the following accordingly:

• If the host restarts the live streaming within 90 seconds:

1. First, the audience will be notified that existing streams in the room stop through the callback onRoomStreamUpdate, and audience need to call the stopPlayingStream method to stop playing the streams.
2. Then, the audience will be notified that new streams are published to the room through the callback onRoomStreamUpdate, and audience need to call the startPlayingStream to start playing the streams again.

• If the host does not restart the live streaming after 90 seconds: The audience will be notified that existing streams in the room stop through the callback onRoomStreamUpdate, and audience need to call the stopPlayingStream method to stop playing the streams.

If the host end gets recovered and published streams successfully: The audience will be notified that new streams are published to the room through the callback onRoomStreamUpdate, and audience can call the startPlayingStream to start playing the streams again.