Data Store

EnableX provides a data storage service to save the video calling data related to your video room, owners, users, and sessions. This data can be retrieved, in-session and post-session, through an API call. Application developers can build video room-based utilities that require in-session data flow and across-session data persistence.

Note: Data storage is a subscription-based service.

Knowing what you can store and for how long you can store it helps you make effective use of the data store service.

Object Hierarchy

Application

  • When you create a video project or a video application using the EnableX Developer Portal, the project or the application is assigned a unique app_id.
  • The video resources are accessible through this app_id. It is the parent object and other objects are placed under it.

Video Room

  • All video rooms created using the Video API are placed under the application object, which is accessible through app_id.
  • Each video room that is created is identified by a unique room_id.
  • Each video room has an owner, who is referred as owner_ref.

Video Session

  • Video sessions are held in a video room.
  • One video room can include one or more video sessions.
  • A video session is identified by a conf_num (Conference Number).

End User

  • End users join a video session from a different type of endpoints or devices.
  • End users connected to a video session are identified using a unique client_id assigned to them.
  • Every time an end user rejoins or reconnects a video session, the user is assigned a new client_id.

Scope of Data Store

You can store the following type of data based on object hierarchy, their identifiers, and other entities in the data store:

Application Data

You can save the in-session availability data at the application-level. This data is accessible across all video rooms and sessions. It is automatically made available to a session when the session is initiated.

This data is retained for 7 days after the application is suspended.

Room Data

You can save the in-session availability data at the room-level. This data is accessible across all the sessions in a video room. It is automatically made available to a session when the session is initiated.

This data is retained until a room is deleted or 7 days after the application is suspended.

Owner Data

You can save the in-session availability data at the room-owner level. This data is accessible to all sessions created in all video rooms owned by the same owner. It is automatically made available to a session when the session is initiated.

This data is retained for 7 days after the application is suspended.

User Data

You can save the in-session availability data at the user-level. This data is accessible to all video rooms when user joins a session.

This data is retained for 7 days after the application is suspended.

Session Data

You can save the in-session availability data at the session-level. This data is accessible within the same session. However, it can be made available in subsequent sessions in the same video room.

This data is retained for 7 days only.

Pre-requisites

Ensure that you meet the following prerequisites to use the Data Store service:

Subscription

The Data Store service is subscription-based, ensure that your EnableX plan includes this add-on.

Owner-level data store

While creating a room, use the unique user-id of the user who is assigned as the owner of a room. While creating a token for the user, specify the value of this user-id for user_ref. When this user joins a video session, the user gets access to the room owner data.

Note: To use the Data Store service effectively, ensure that a unique user-id is specified for owner_ref and user_ref while creating a room and token for the room owner.

User-level data store

Use the unique user-id for each user as user_ref while creating a token for them. Users can access their own user data when they join a video session. Any data saved at the user level will be saved against the user_ref of the user who has joined.

Note: To use the Data Store service effectively, ensure that a unique user-id is specified for user_ref while creating a token.

SDK Support

All Video SDKs include methods to store and retrieve different scopes of data.

Note: These examples use Web SDKs only. For other SDKs, refer to the related SDK Documentation.

The following data scope is supported by SDKs:

  • Application Level: Read-only support. Cannot change data.
  • Room Level: Can create, edit, and delete data. JSON objects and arrays can be defined.
  • Room Owner Level: Read-only support. Cannot change data.
  • Session Level: Can create, edit, and delete data. JSON objects and arrays can be defined.
  • User Level: Can create, edit, and delete data. JSON objects and arrays can be defined.

Retrieve from Data Store

Use the following method to retrieve different scopes of data to use them in a video session.

  • Method: getCustomData(options, callback)
  • Parameters:
    • options: A JSON object with configurable options to retrieve the right data.
      • scope: Accepts enumerated values: app, user, owner, session, and room.
        • Withapp scope, no further qualifier is needed. It returns app-level custom data.
        • With owner scope, no further qualifier is needed. It returns custom data for the connected room's owner-ref.
        • With room scope, no further qualifier is needed. It returns custom data for connected room.
        • With user scope, user_ref receives custom data for the specified user.
        • With session scope, optionally, either session or conf_num qualifier can be used to get data for requested sessions. If none of them is used, it returns the current session data.
      • user_ref:
        • It is required with user scope. It returns custom data for the given user_ref.
        • It is provided as an option with session scope. It returns session data for the given user_ref.
      • session: It is optional and can be used with session scope. It accepts the following values:
        • all: For all session data of the same room.
        • last: For the last session data of the same room.
        • conf_num: It is optional and can be used with session scope. It takes conf_num of a session for which data is needed.

Example: Scope=user

Note: The Options parameter can contain different keys for querying different scopes. To fetch a user named "JOE", pass the parameter like this:

var Options = {	
	"scope": "user",
	"user_ref": "JOE"	
}

You will receive the following response:

{	"result": 0,              
	"clientId": "",             
	"name": "",                  
	"user_ref": "",              
	"role": "participant",       
	"data": {							// This is your own Data  
		"custom_data1": "String",
		"custom_data2": "String",
		"in_session_new_data": "String", 
		"in_session_new_data": "String"  
	}
}

Set and Reset Data

Use the following method to set and update the data of different scope in a video session.

  • Method: setCustomData(scope, data, callback)
  • Parameters:
    • scope: Enumerated values: user, room, session. Each scope has a different data structure.
    • data: A JSON object related to scope.

Example: The data parameter for the user scope. It is executed from the endpoint only to affect the connected user's data.

var data = {
	"custom_data1": "String",			// update
	"custom_data2": "String",
	"in_session_new_data": "String",	// new
	"in_session_new_data": "String"
}

Example: E.g., data parameter for the session scope. It is executed from any endpoint to affect the current session only.

var session_data = {
	"poll": {
		"question: "String",	 
		"options": [{
			"opt": "String",
			"response": Number	
		}]
	}
}

Refer SDKs

For detailed SDK implementation details, visit:

Virtual Background | Live Video Calling Feature