Does ZEGO SDK support a fast reconnection for temporary disconnection?

The ZEGO Web 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 roomStateUpdate callback.

For other users in the room, to receive updates on the status of specified users in the room, call the roomStateUpdate method. (Remember to set the userUpdate 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 roomStateUpdate(roomID, "CONNECTING", 0, extendedData) and the roomStateUpdate(roomID, "CONNECTED", 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 roomUserUpdate(roomID, 'ADD', 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 roomUserUpdate(roomID, 'ADD', userList) callback and is notified that the reconnection attempt is ongoing.
• T4 ≈ T3 + 90s: The ClientB receives the roomUserUpdate(roomID, 'DELETE', userList) callback and is notified that the ClientA is disconnected/offline.
• T5 = T3 + time (less than 5 minustes): The ClientA gets reconnected within the default reconnection duration. The ClientA receives the callback roomStateUpdate(roomID, 'CONNECTED', 0, extendedData) and is notified that the reconnection attempt is successful.
• T6 ≈ T5 + 100ms: Due to network transmission delays, the ClientB receives the roomUserUpdate(roomID, 'ADD', userList) callback about 100ms later and is notified that the ClientA has reconnected successfully.
• T7 = T3 + 5min: If the ClientA fails to re-join the room for over 5 minutes, the SDK will not try to reconnect again. The ClientA receives the roomStateUpdate(roomID, 'DISCONNECTED', 1002031, 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 publisherStateUpdate.

In this callback, when the state is NO_PUBLISH 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 playerStateUpdate.

In this callback, when the state is NO_PLAY 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

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 roomStreamUpdate, 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 roomStreamUpdate, 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 playerStateUpdate (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 roomStreamUpdate, 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 roomStreamUpdate, and audience in the room can call the startPlayingStream to start playing the streams again.

2.3 Audience side: how to handle when the browser process of the host is killed or the page crashes

When the host's browser process is killed or the page crashes, and the host does not restart the live streaming for a while, the audience will be notified that existing streams in the room stop through the callback roomStreamUpdate.

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 roomStreamUpdate, 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 roomStreamUpdate, 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 roomStreamUpdate, and audience need to call the stopPlayingStream method to stop playing the streams.

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