A communication channel is provided between IFRAME Embed and the Parent Window, allowing application developers to enhance engagement within the session and customize the UI/UX. Developers can execute predefined actions in the Embed from the Parent Window and receive notifications about statuses and events occurring in the 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 evtdata = e;
// If you encode the notification in JSON before sending them,
// then decode here
var data_decoded = JSON.parse(evtdata);
// 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",
"user-connection",
"stream-updates",
"messaging"
]
}
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 notificationsroom-connection– To receive notification related to room connection, disconnection, re-connection etc.- user-connection – To receive notification related to any user connecting to room or disconnecting from room.
stream-updates– To receive notification related to local and remote stream attribute, configuration updates.messaging– To receive notification related to custom signaling, chat (coming up) etc.
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",
"user-connection",
"stream-updates",
"messaging"
]
}
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 notificationsroom-connection– To stop receiving notification related to room connection, disconnection, re-connection etc.- user-connection – To stop receiving notification related to any user connecting to room or disconnecting from room.
stream-updates– To stop receiving notification related to local and remove stream attribute, configuration updates.messaging– To stop receiving notification related to custom signaling, chat (coming up) etc.
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. Usetrueto 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. Usefalseto disconnect immediately without any prompt
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 Streamrtmp_endpoint– The RTMP Endpoint URL where the stream to be sentrtmp_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"
}
2.5 UI / UX
These set of actions are related to UI and UX of the Video Embed on ongoing Video Session.
2.5.1 Change Video Layout
This is to change VIdeo Grid Layout either to Gallery View or Leader View at RTMP End Point and/or each End Point.
To change Layout, send the following message:
{
"action": "change-layout",
"data": {
"target": "rtmp",
"layout": "leader" }
}
Data Object:
target– Values: rtmp, all. When “rtmp” is used, the layout is affected at RTMP End Point only. When “all” is used, the layout is affected at all End Points.layout– Values: leader, gallery. The layout to be used.
2.6 Messaging
These set of actions are related to signaling and messaging among users in the Video Session..
2.6.1 Send Custom Signaling
This allows sending a custom data structure to all users in a Video Session. The system does not interact with individual endpoints but simply broadcasts the message among users as a signaling mechanism. It is recommended to use a limited-size custom data structure for broadcasting.
Define your data structure and send the following message for broadcasting:
{
"action": "signal",
"data": {
/* Define your custom object here */
}
}
Data Object:
data– Object. All Keys are be defined by you to broadcast among users.
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 Roomconf_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 needn’t subscribe to receive this notification.
JSON Message: Parent Window receives the following notification
{
"notification": "room-disconnected",
"data": {
"message": "Reason for disconnection"
}
}
You may get following reasons for disconnection:
- Session expired
- Room access denied
- Failed to reconnect
- Disconnected by Moderator
- Unexpected disconnection
- Normal disconnect
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 User Connection
This is a User Connection Notification Group. This covers notification related to user connection and disconnection. To receive some of these notifications, Parent Page need to subscribe to user-connection Notification Group.
3.3.1 UserConnected
This is to notify that the a new user got connected to the Virtual Room.
JSON Message: Parent Window receives the following notification
{
"notification": "user-connected",
"data": {
"clientId": "XOXO",
"name": "John",
"role": "participant"
}
}
Data Object:
clientId– The Unique ID assigned to each user connected to Video Room.name-Name of the user connected the Video Room.role-Role of the user. It may have the following enumerated datamoderator, participant, viewer, audience
3.3.2 UserDisconnected
This is to notify that the a user got disconnected from the Virtual Room.
JSON Message: Parent Window receives the following notification
{
"notification": "user-disconnected",
"data": {
"clientId": "XOXO",
"name": "John",
"role": "participant"
}
}
Data Object:
clientId– The Unique ID assigned to each user connected to Video Room.name-Name of the user disconnected from the Video Room.role-Role of the user. It may have the following enumerated datamoderator, participant, viewer, audience
3.4 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.4.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.4.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.4.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.4.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.5 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.5.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 Streamrtmp_endpoint– The RTMP Endpoint URL where the stream to be sentrtmp_key– The RTMP Key
3.5.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.6 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.6.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.6.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.6.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.6.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.6.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": {}
}
3.7 Messaging
This is a Messaging Group. This covers notification related to inter user messaging and signaling. Parent Page need to subscribe to “messaging” Notification Group to receive these notifications.
3.7.1 Custom Signal Received
This is to notify that you have received a signal with custom data structure to be used by your Parent Window to use it anyway you want.
JSON Message: Parent Window receives the following notification
{
"notification": "signal-received",
"data": {
/* Custom data here */
}
}