Skip to main content

Events

Events​

The Video Conference in SuperViz SDK offers a range of events that allow you to monitor and respond to various interactions and changes within the meeting in real-time. These events provide valuable insights into participant actions, meeting state transitions, and more.

DESTROY​

The DESTROY event will be dispatched when the room.removeComponent() is used or when the participant leaves the meeting room.

Here is an implementation on how to catch the dispatched event:

video.subscribe('destroy', onDestroy);

function onDestroy() {
	// do something
}

MEETING_DEVICES_CHANGE​

The MEETING_DEVICES_CHANGE event is triggered when there is a change in the local participant device list. E.g. This event will be triggered when the participant connects a headphone on the laptop.

Here is an implementation on how to catch the dispatched event:

video.subscribe('meeting.devices-change', onDevicesChanges);

function onDevicesChanges(payload) {
	// do something
}

On the callback function, you will receive the following argument:

TypeDescription
DeviceEventRepresents the status of the devices available for the local participant.

MEETING_CONNECTION_STATUS_CHANGE​

The MEETING_CONNECTION_STATUS_CHANGE event is triggered when there is a change in the connection status of the participant in the meeting. This event provides real-time updates about the quality and availability of the audio/video service.

By monitoring this event and interpreting the status values, you can implement responsive actions, such as advising participants to turn off video in case of a BAD connection or handling reconnection scenarios when LOST_CONNECTION occurs.

You can check the possible values for connection status in the end of the page.

Here is an implementation on how to catch the dispatched event:

video.subscribe('meeting.connection-status-change', onConnectionStatusChange);

function onConnectionStatusChange(status) {
	// do something
}

On the callback function, you will receive the following argument:

TypeDescription
MeetingConnectionStatusRepresents the updated connection status of the Video Conference meeting.

MEETING_NO_HOST_AVAILABLE​

The MEETING_NO_HOST_AVAILABLE event will be triggered when a guest or audience member enters the meeting, but there’s no host available yet.

If a host is the first to enter the meeting the event won’t be dispatched.

Here is an implementation on how to catch the dispatched event:

video.subscribe('meeting.no-host-available', onNoHostAvaliable);

function onNoHostAvaliable() {
	// do something
}

MEETING_HOST_AVAILABLE​

The MEETING_HOST_AVAILABLE event will be triggered when the host enters the meeting after guests and audience members have already joined.

If a host is the first to enter the meeting the event won't be dispatched.

Here is an implementation on how to catch the dispatched event:

video.subscribe('meeting.host-available', onHostAvailable);

function onHostAvailable() {
	// do something
}

MEETING_HOST_CHANGE​

The MEETING_HOST_CHANGE event will be triggered when a new participant is giving the host capabilities for the current meeting.

Here is an implementation on how to catch the dispatched event:

video.subscribe('meeting.host-change', onHostChange);

function onHostChange() {
	// do something
}

On the callback function, you will receive the following argument

TypeDescription
stringThe ID for the new participant host.

Example:

"<USER_ID>"

MEETING_KICK_PARTICIPANT​

Whenever a host kicks one participant out of the meeting, the MEETING_KICK_PARTICIPANT event will be dispatched.

Here is an implementation on how to catch the dispatched event:

video.subscribe('my-participant.joined', onMeetingKickParticipant);

function onMeetingKickParticipant(participantId) {
	// do something
}

On the callback function, you will receive the following argument:

TypeDescription
stringID of the kicked participant.

MEETING_KICK_PARTICIPANTS​

The MEETING_KICK_PARTICIPANTS event is triggered when two or more participants in the room, one designated as a host and the other as a non-host (typically a guest). For the event to occur, the host must leave the room, leaving only the non-host inside. This situation results in the room being left without a host.

Here is an implementation on how to catch the dispatched event:

video.subscribe('meeting.kick-all-participants', onKickParticipants);

function onKickParticipants() {
	// do something
}

MEETING_PARTICIPANT_AMOUNT_UPDATE​

Use the MEETING_PARTICIPANT_AMOUNT_UPDATE to be notified if the number of participants in a meeting has changed.

Here is an implementation on how to catch the dispatched event:

video.subscribe('meeting.amount-of-participants-update', onParticipantAmountUpdate);

function onParticipantAmountUpdate(participantsAmount) {
	// do something
}

On the callback function, you will receive the following argument:

TypeDescription
numberThe number of participants at the meeting after the change.

MEETING_PARTICIPANT_JOINED​

The MEETING_PARTICIPANT_JOINED is dispatched when a participant enters the meeting room.

Here is an implementation on how to catch the dispatched event:

video.subscribe('meeting.participant-joined', onParticipantJoined);

function onParticipantJoined(participant) {
	// do something
}

On the callback function, you will receive the following argument:

TypeDescription
ParticipantThe participant details that had joined the meeting triggered the event.

Example:

{
    "id": "<USER_ID>",
    "color": "#878291",
    "type": "host",
    "name": "<USER_NAME>",
    "isHost": true,
}

MEETING_PARTICIPANT_LEFT​

The MEETING_PARTICIPANT_LEFTis dispatched when a participant leaves the meeting room.

Here is an implementation on how to catch the dispatched event:

video.subscribe('meeting.participant-left', onParticipantLeft);

function onParticipantLeft(participant) {
	// do something
}

On the callback function, you will receive the following argument:

TypeDescription
ParticipantInformation of the participant that had left the meeting.

Example:

{
    "id": "<USER_ID>",
    "color": "#31E0B0",
    "type": "host",
    "name": "<USER_NAME>",
    "isHost": false
}

MEETING_PARTICIPANT_LIST_UPDATE​

Use the MEETING_PARTICIPANT_LIST_UPDATE to be notified with the current participants list, whenever there is a change on the list of participants of the meeting.

Here is an implementation on how to catch the dispatched event:

video.subscribe('meeting.participant-list-update', onParticipantListUpdate);

function onParticipantListUpdate(participants) {
	// do something
}

On the callback function, you will receive the following argument:

TypeDescription
Participant[]Actual list of participants at the meeting.

Example:

[
	{
	    "id": "<USER_ID>",
	    "color": "#878291",
	    "type": "host",
	    "name": "<USER_NAME>",
	    "isHost": true
	}
]

MEETING_SAME_PARTICIPANT_ERROR​

Dispatched when a participant tries to join the same meeting at the same time. In this case, the SDK dispatches the error and destroys the first instance of the SDK, leaving only the last instance that is currently being used.

Here is an implementation on how to catch the dispatched event:

video.subscribe('meeting.same-participant-error', onSameParticipantError);

function onSameParticipantError(error) {
	// do something
}

On the callback function, you will receive the following argument:

TypeDescription
stringError message from the dispatched event.

MEETING_START​

Use the MEETING_START event to be notified when the Video Conference is initialized.

Here is an implementation on how to catch the dispatched event:

video.subscribe('meeting.start', onMeetingStart);

function onMeetingStart() {
	// do something
}

MEETING_STATE_UPDATE​

The Video Conference operates through a series of distinct states to ensure the meeting experience. The MEETING_STATE_UPDATE event enables you to monitor and react to these state transitions.

Monitoring these states allows you to provide real-time feedback to participants and implement dynamic behavior based on the current state of the Video Conference. E. g. When the state is MEETING_READY_TO_JOIN it confirms that the user has already consent devices permissions and it’s ready to join the meeting.

You can see a complete list of meeting states at the end of the page. Here is an implementation on how to catch the dispatched event:

video.subscribe('meeting.state-update', onStateUpdate);

function onStateUpdate(state) {
	// do something
}

On the callback function, you will receive the following argument:

TypeDescription
MeetingStateRepresents the current state of the Video Conference meeting.

MEETING_WAITING_FOR_HOST​

The MEETING_WAITING_FOR_HOST event will be triggered when a guest or audience member of the meeting tries to join the meeting, but there’s no host available yet. It will be triggered again, with the value false, when the host joins the room.

If a host is the first to enter the room the event won’t be dispatched. Here is an implementation on how to catch the dispatched event:

video.subscribe('meeting.waiting-for-host', onWaitingForHost);

function onWaitingForHost(waiting) {
	// do something
}

On the callback function, you will receive the following argument:

TypeDescription
booleanWhen true, this event is dispatched to indicate the absence of a host. When false, it is dispatched upon the host's entry into the room.

MY_PARTICIPANT_JOINED​

This event will be dispatched when the local participant enters the meeting.

Here is an implementation on how to catch the dispatched event:

video.subscribe('my-participant.joined', onMyParticipantJoined);

function onMyParticipantJoined(participant) {
	// do something
}

On the callback function, you will receive the following argument:

TypeDescription
ParticipantParticipant that triggered the event by entering the meeting.

Example:

{
    "id": "<USER_ID>",
    "color": "#878291",
    "type": "host",
    "name": "<USER_NAME>",
    "isHost": true
}

MY_PARTICIPANT_LEFT​

This event will be dispatched when the local participant leaves the meeting.

Here is an implementation on how to catch the dispatched event:

video.subscribe('my-participant.left', onMyParticipantLeft);

function onMyParticipantLeft(participant) {
	// do something
}

On the callback function, you will receive the following argument:

TypeDescription
ParticipantParticipant that triggered the event by leaving the meeting.

Example:

{
    "id": "<USER_ID>",
    "color": "#878291",
    "type": "host",
    "name": "<USER_NAME>",
    "isHost": true
}

FRAME_DIMENSIONS_UPDATE​

The Video Conference, when initialized, inserts a SuperViz-enabled iframe into the Document Object Model (DOM). You can adjust the iframe behavior thorough the property offset on the initialization.

Once the frame dimensions change for any reason, you can catch the iframe dimensions using the FRAME_DIMENSIONS_UPDATE event. Here is an implementation on how to catch the dispatched event:

video.subscribe('frame.dimensions-update', onFrameDimensionsUpdate);

function onFrameDimensionsUpdate(dimensions) {
	// do something
}

On the callback function, you will receive the following argument:

TypeDescription
DimensionsRepresents the dimensions of the Video Conference frame.

Types definition​

DeviceEvent​

Type: enum

This enum helps to understand the status of the devices available for the local participant.

Here are the possible states and their meanings:

StateDescription
NO_CAMNo camera is available for the local participant.
NO_DEVICESNo devices are currently connected.
DEVICES_BLOCKEDDevice access is blocked for the participant.
DEVICES_CAM_BLOCKEDCamera access is blocked for the participant. Perhaps because it’s been used by other applications.
DEVICES_INITIALIZATION_ERRORThere was an error during device initialization.
DEVICES_UNKNOWN_ERRORAn unknown error occurred with the participant's devices.
DEVICES_ALLOWEDAll device access is granted by the participant.

Dimensions​

Type: object

An object that represents the Video Conference dimensions on the component’s frame.

NameTypeDescription
widthnumberThe width of the frame represented in pixels.
heightnumberThe height of the frame represented in pixels.

Example:

{
    "width": 921,
    "height": 678
}

Participant​

Type: object

An object describing the participant information, like name and avatar.

NameTypeDescription
idstringIdentifier of the participant who is entering the room. Usually, this ID matches the internal ID of your users.
avatarAvatarParticipant avatar information.
colorstringUnique color for the participant in the meeting, is used to identify the user cursor and avatar/laser in 3D space.
isHostbooleanIndicates if the participant is the current host of the room.
namestringThe name of the participant who will enter the room.
typeParticipantTypeUser it to give proper user permission in the room. Options are host, guest, and audience.

Example:

"participant": {
  "id": "<USER-ID>",
  "name": "<USER-NAME>",
  "type": "host",
	"color": "#878291",
	"avatar": {
		"imageUrl": "https://<PATH>",
		"model3DUrl": "https://<PATH>", 
	}
}

MeetingConnectionStatus​

Type: enum

The MeetingConnectionStatus serves as a dynamic indicator of the real-time connection quality and availability of the audio/video service. This enumeration defines a set of distinct values, each reflecting a specific state of the meeting's connection, allowing you to precisely monitor and respond to the meeting's operational status.

This enum has the following possible statuses:

StatusValueDescription
NOT_AVAILABLE0Indicates that the audio/video service is disconnected.
GOOD1Represents good connection quality, ensuring a stable and reliable audio/video experience.
BAD2Indicates a bad connection quality. It’s indicated to encourage the participants to consider turning off video to enhance the experience.
POOR3Signifies a poor connection, often due to participant connections and/or PC specifications not meeting the minimum requirements for a smooth audio/video experience.
DISCONNECTED4Indicates that audio/video transmission has been interrupted, with no network packets sent or received for at least 10 seconds.
RECONNECTING5Occurs during a reconnection process triggered by a loss of connection.
LOST_CONNECTION6Indicates a complete loss of connection to the audio/video service.

MeetingState​

Type: enum

Represents the current state of the Video Conference meeting. This value reflects one of the possible states indicating the operational status of the meeting component. You can utilize this information in your callback function to respond to and manage the meeting's dynamic behavior based on its state.

Here are the possible states and their meanings:

StateValue
MEETING_FAILED-1Indicates a failure in the meeting, requiring attention or troubleshooting.
MEETING_DISCONNECTED0Indicates a state where the meeting is not connected.
MEETING_INITIALIZING1Signifies the meeting is in the process of initialization.
MEETING_READY_TO_JOIN2Confirms that the meeting was prepared for participants to join, meaning that device permissions were consent and everything is working.
MEETING_CONNECTING3Indicates an ongoing connection process that happens after the participant joins the meeting.
MEETING_CONNECTED4Confirms that the meeting is successfully connected.
MEETING_RECONNECT5Occurs when the meeting reconnects after a disruption.
FRAME_INITIALIZING6Indicates the initialization of the meeting iframe.
FRAME_INITIALIZED7Indicates a successfully initialized meeting iframe.
FRAME_UNINITIALIZED8Represents an uninitialized meeting iframe.