EnableX provides a communication channel between IFRAME Embed and Parent Window. This will enable Application Developers with a tool of engagement with Embed in-session to create UI/UX. This will help them to execute predefined action-execution in Embed from Parent and get notified about status and events happening in Embed.

Table of Contents

1 How it works?

JS Framework of Messaging between Browser Window Objects (parent, child, named-window) would help in this process. A window sends a message with JSON Data to other window which listens to incoming message and takes action on it.

So, Embed will listen to Message sent by Parent Page to take action on it and will also generate Message to Parent Page to notify various events.

To understand the overall workflow, follow the section below explanations with Code Samples:

1.1 Action from Parent Window

Example: Parent Window sends message to Embed to Start Streaming:

const message = JSON.stringify({
    action: 'start-live-streaming',
    data: {
	"name": "Youtube",
	"rtmp_endpoint": "rtmp://a.rtmp.youtube.com/live2",
	"rtmp_key": "XOXOXO"
	}
});

EmbedIFrameElementID.contentWindow.postMessage(message, '*'); 
// EmbedIFrameElementID is the "id" of IFRAME Tag that uses Low Code Meeting URL

1.2 Listener at Parent Window

Example: Parent Window listens to notification message from Embed and takes appropriate action:

window.addEventListener(‘notification’, function (e) {
	// Get the sent data
	var data = e.data;

	// If you encode the notification  in JSON before sending them,
	// then decode here
	var data_decoded = JSON.parse(data);
	
	// data_decoded example:
	/*
	{
	    notification: ‘room-connected',
	    data: {
		"room_name": "John’s Room",
		"conf_num": "XOXOXO"
		}
	}
	*/

	switch (data_decoded.notification) {
		case ‘room-connected’:
			doDBPost(data_decoded.data);
			break;
		case 'other-notice':
			do_other_notice()
			break;
	}
});

2 Actions

Here are the list of Actions that can be passed from Parent Window to Embed in the form of JSON Object. Note that this Document only provides the format of JSON Object that is used effectively in message passing to get an action executed.

2.1 Notification Subscription

Parent window must subscribe for Event Notifications from Embed to start receiving. Embed will keep sending Notifications of subscribed “Notification Groups” to Parent until unsubscribed.

2.1.1 Subscribe to start receiving notifications

This is to subscribe to receive notifications of various events and action status from the Embed. You need to subscribe to one or more Notification Group(s) to start receive all event notifications under that group.

e.g. if you subscribe to room-connection group, embed will notify you of room connection, disconnection, reconnection etc.

{
  "action": "subscribe-notification",
  "data": [   /* one or more notification group */
    "live-streaming",
    "room-connection",
    "stream-updates"
  ]
}

Data Object: It contains an array of notification groups to subscribe to receive notifications related to that group until unsubscribed.

  • live-streaming– To receive start / stop live streaming notifications
  • room-connection – To receive notification related to room connection, disconnection, re-connection etc.
  • stream-updates – To receive notification related to local and remove stream attribute, configuration updates.

2.1.2 Unsubscribe to stop receiving notifications

This is to unsubscribe from receiving notifications of various events from Embed. You may opt-out from one or more notification groups by passing multiple group names.

To unsubscribe notification from one or more notification groups, post the following:

{
  "action": "unsubscribe-notification",
  "data": [
    "live-streaming",
    "room-connection",
    "stream-updates"
  ]
}

Data Object: It contains an array of notification groups to unsubscribe to stop receiving notifications related to that group.

  • live-streaming– To stop receiving start / stop live streaming notifications
  • room-connection – To stop receiving notification related to room connection, disconnection, re-connection etc.
  • stream-updates – To stop receiving notification related to local and remove stream attribute, configuration updates.

To unsubscribe notification from all notification groups, post the following:

{
  "action": "unsubscribe-notification",
  "data": []
}

2.2 Room Connection

2.2.1 Disconnect from Room

This is to disconnect from the Virtual Room. Once disconnected, the Embed is not longer in Video Session and will not able to communicate with the Virtual Room anyway until it rejoins the Session.

To disconnect from Session with a Prompt to confirm exit from Session, send the following message:

{
  "action": "disconnect-room",
  "data": {
    "alert": true
  }
}

Data Object:

  • alert– Boolean. Use true to disconnect session only if user confirms through given Prompt Window

To disconnect from Session immediately without a Prompt to confirm exit from Session, send the following message:

{
  "action": "disconnect-room",
  "data": {
    "alert": false
  }
}

Data Object:

  • alert– Boolean. Use false to disconnect immediately without any prompt

2.2.2 Destroy Video Session

A Moderator or Host can destroy Virtual Room to stop the Session immediately. Once the Session is destroyed, all connected users will be disconnected automatically from the Room.

To destroy Session with a Prompt to confirm, send the following message:

{
  "action": "destroy-room",
  "data": {
    "alert": true
  }
}

Data Object:

  • alert– Boolean. Use true to destroy session only if user confirms through given Prompt Window

To destroy Session immediately without a Prompt to confirm, send the following message:

{
  "action": "destroy-room",
  "data": {
    "alert": false
  }
}

Data Object:

  • alert– Boolean. Use false to destroy session immediately without any prompt

Note: This a Host only feature, so must be executed from the Moderator/Host Side of UI only.

2.3 Stream Updates

These set of actions are related to updated local and remote stream media tracks, attributes and configuration.

2.3.1 Mute Video

This is to stop Video from Local Stream. The Stream immediately drops Video Track until unmuted.

To mute Video, send the following message:

{
  "action": "mute-video"
}

2.3.2 Unmute Video

This is to unmute Video in Local Stream. The Stream immediately adds Video Track.

To unmute Video, send the following message:

{
  "action": "unmute-video"
}

2.3.3 Mute Audio

This is to mute Audio from Local Stream. The Stream immediately drops Audio Track until unmuted.

To mute Audio, send the following message:

{
  "action": "mute-audio"
}

2.3.4 Unmute Audio

This is to unmute Audio in Local Stream. The Stream immediately adds Audio Track.

To unmute Audio, send the following message:

{
  "action": "unmute-audio"
}

2.4 Live Streaming

These set of actions are related to Live Streaming of ongoing Video Session to an RTMP Endpoint for content distribution to larger audience.

Note: These are Host only features. So, these messages must be sent from the Moderator/Host Side of UI only.

2.4.1 Start Live Streaming

This is to start Live Streaming of ongoing Video Session to an RTMP Endpoint.

To start Live Streaming, send the following message:

{
  "action": "start-live-streaming",
  "data": {
    "name": "Youtube",
    "rtmp_endpoint": "rtmp://a.rtmp.youtube.com/live2",
    "rtmp_key": "XOXOXO"
  }
}

Data Object:

  • name – Plain Text to describe the Stream
  • rtmp_endpoint – The RTMP Endpoint URL where the stream to be sent
  • rtmp_key – The RTMP Key

2.4.2 Stop Live Streaming

This is to stop ongoing Live Streaming of the Video Session from all RTMP End Points.

To stop Live Streaming, send the following message:

{
  "action": "stop-live-streaming"
}

3 Notifications

Video Embed sends out notifications to Parent Window to notify various events, status of actions in the Video Session. Parent Window must subscribe to receive notification, otherwise notifications are not generated by the Video Embed.

Parent Window must listen to the Events and take appropriate action.

3.1 Subscription

This notification group need not be subscribed. and area always available. These notifications are generated by Video Embed as a response of Notification Subscription and Subscription process.

3.1.1 Notification Subscribed

This is to notify that Parent Window has successfully subscribed to receive one or more notification groups.

JSON Message: Parent Window receives the following notification

{
  "notification": "notification-subscribed",
  "data": [
    "live-streaming",
    "room-connection"
  ]
}

Data Object: It is an array of notification groups to which the Parent Window has subscribed to receive.

3.1.2 Notification Unsubscribed

This is to notify that Parent Window has successfully unsubscribed from receiving one or more notification groups.

JSON Message: Parent Window receives the following notification

{
  "notification": "notification-unsubscribed",
  "data": [
    "live-streaming",
    "room-connection"
  ]
}

Data Object: It is an array of notification groups to which the Parent Window has subscribed to receive.

3.2 Room Connection

This is a Room Connection Notification Group. This covers notification related to room connection, disconnection and auto-reconnection into the Room. To receive some of these notifications, Parent Page need to subscribe to room-connection Notification Group.

3.2.1 Room Connected

This is to notify that the Video Embed is connected to Virtual Room for communication. Parent page needn’t subscribe to receive this notification.

JSON Message: Parent Window receives the following notification

{
  "notification": "room-connected",
  "data": {
    "room_name": "John's Room",
    "conf_num": "XOXOXO"
  }
}

Data Object:

  • room_name – Name of the Virtual Room
  • conf_num – Conference Number of Session ID. It uniquely identifies the Video Session

3.2.2 Room Not Connected

This is to notify that the Video Embed is not connected to Virtual Room for communication. Parent page needn’t subscribe to receive this notification.

JSON Message: Parent Window receives the following notification

{
  "notification": "room-not-connected",
  "data": {}
}

3.2.3 Room Disconnected

This is to notify that the Video Embed is disconnected from the Video Session. No longer communication is feasible hence forth until the Embed rejoins or reconnects the Virtual Room. Parent page needs to subscribe to room-notification group to receive this notification.

JSON Message: Parent Window receives the following notification

{
  "notification": "room-disconnected"
}

3.2.4 Room Re-connected

This is to notify that the Video Embed is reconnected to the Virtual Room. The Embed resumed communication. Parent page needs to subscribe to room-notification group to receive this notification.

JSON Message: Parent Window receives the following notification

{
  "notification": "room-reconnected"
}

3.3 Stream Updates

This is a Stream Updates Notification Group. This covers notification related to local stream configuration, track, attribute updates. To receive one or all notification, Parent Page must subscribe to stream-updates Notification Group.

3.3.1 Video Muted

This is to notify that the Video is muted or stopped in the Local stream.

JSON Message: Parent Window receives the following notification

{
  "notification": "video-muted"
}

3.3.2 Video Unmuted

This is to notify that the Video is unmuted or restarted in the Local stream.

JSON Message: Parent Window receives the following notification

{
  "notification": "video-unmuted"
}

3.3.3 Audio Muted

This is to notify that the Audio is muted or stopped in the Local stream.

JSON Message: Parent Window receives the following notification

{
  "notification": "audio-muted"
}

3.3.4 Audio Unmuted

This is to notify that the Audio is unmuted or restarted in the Local stream.

JSON Message: Parent Window receives the following notification

{
  "notification": "audio-unmuted"
}

3.4 Live Streaming

This is a Live Streaming Notification Group. To receive one or all notification, Parent Page must subscribe to live-streaming Notification Group.

3.4.1 Live Streaming Started

This is to notify that the Live Streaming has started.

JSON Message: Parent Window receives the following notification

{
    "notification": "live-streaming-started",
    "data": {
	"name": "Youtube",
	"rtmp_endpoint": "rtmp://a.rtmp.youtube.com/live2",
	"rtmp_key": "XOXOXO"
	}
}

Data Object:

  • name – Plain Text to describe the Stream
  • rtmp_endpoint – The RTMP Endpoint URL where the stream to be sent
  • rtmp_key – The RTMP Key

3.4.2 Live Streaming Stopped

This is to notify that ongoing Live Streaming of the Video Session to all RTMP End Points are stopped.

JSON Message: Parent Window receives the following notification

{
    "notification": "live-streaming-stopped",
    "data": {}
}

3.5 Media Access

This is a Media Access Notification Group. This covers notification related to Media Device Accessibility. These notifications are always available, Parent Page needn’t subscribe to the Notification Group.

3.5.1 Media Access Denied

This is to notify that the Video Embed failed to get Media Device Access (Media Device is a general term covers Camera and Microphone Devices). An end point may or may not join Video Room if Media Device Access is denied.

JSON Message: Parent Window receives the following notification

// When room not connected
{
  "notification": "media-access-denied",
  "data": {
    "message": "Media access denied. Room not connected."
  }
}

// When room is connected without Media Device Access
{
  "notification": "media-access-denied",
  "data": {
    "message": ""Mic and Camera access denied"
  }
}

3.5.2 Camera Access Denied

This is to notify that the Video Embed failed to get Camera Device Access. An end point may or may not join Video Room if Camera Device Access is denied.

JSON Message: Parent Window receives the following notification

{
  "notification": "camera-access-denied",
  "data": {}
}

3.5.3 Camera Access Allowed

This is to notify that the Video Embed is allowed access to Camera Device.

JSON Message: Parent Window receives the following notification

{
  "notification": "camera-access-allowed",
  "data": {}
}

3.5.4 Microphone Access Denied

This is to notify that the Video Embed failed to get Microphone Device Access. An end point may or may not join Video Room if Microphone Device Access is denied.

JSON Message: Parent Window receives the following notification

{
  "notification": "mic-access-denied",
  "data": {}
}

3.5.5 Microphone Access Allowed

This is to notify that the Video Embed is allowed access to Microphone Device.

JSON Message: Parent Window receives the following notification

{
  "notification": "mic-access-allowed",
  "data": {}
}