Version 07/21
There are two video conference room integration ways:
- Codeless – just copy an URL, paste iframe on your page… and join a call.
- API-based – use API for fine-tuning and integration with your platforms or enterprise internal systems.
Embedded video meetings into an application or website via iFrame or Server API/Client API allow your team to build faster and ship more often.
- URL Attributes for rich customization
- Attributes details
-
- &accessToken=<token>
- &autoplayWithoutAudioTrack=<true|false>
- &canRecord=<true|false>
- &controlsDisabled=<true|false>
- &disableChat=<true|false>
- &displayName=<name>
- &itisparticipant=<true|false>
- &lang=<code>
- &minimizeTiles=<true|false>
- &nameScreenDisabled=<true|false>
- &peerId=<id>
- &role=<role>
- &sortPeers=<true|false>
- &startWithFS=<true|false>
- &token=<jwt>
- &tokenLifetime=<milliseconds>
- &video=<url>
- &waitingRoom=<true|false>
-
- Debug and Dev URL attributes
- Room types for video conferencing
Get started
Create a meeting in a browser:
1. Open https://meet.gcorelabs.com/new
2. Click on Create conference button.
3. Room URL will automatically be created for you.
4. Click on Join.
5. Send the URL (e.g https://meet.gcorelabs.com/call/?roomId=serv0testroom) to other attendees for joining the video call.
6. Embed the video call room on your website or app via an iframe. The iframe’s src attribute is specified as the URL.
Example:
<iframe allow="camera; microphone; fullscreen; display-capture" src=" https://meet.gcorelabs.com/call/?roomId=serv0testroom"></iframe>
You can customize the meeting room with URL attributes.
Example:
https://meet.gcorelabs.com/call/?roomId=serv0testroom&displayName=John%20Snow
Codeless integration
Embed a meeting room on a website
Embedding a meeting into a service or app requires using an iframe with the src attribute specified as the URL.
Read the Allowed domains section to learn how to allow your website’s domain so that browsers don’t block the iframe.
The following special permissions required for video calling should be set into iframe: allow=" camera; microphone; fullscreen; display-capture"
Example:
<iframe
src="https://meet.gcorelabs.com/call/?roomId=serv0testroom"
allow="camera; microphone; fullscreen; display-capture"
></iframe>
Mobile apps integration
Embedding in Android app
Embedding in the Android system requires the use of the WebView class.
To allow video call room to access the camera, you need to do the following:
- Override the WebChromeClient.onPermissionRequest method to avoid the default implementation. You can just return true.
- Add the &nameScreenDisabled=true parameter to the room URL and call the Join Client API method.
Embedding in iOS app
WKWebView supports embedding pages that use WebRTC from iOS 14.5 onwards.
To support older iOS versions one of the following options is recommended:
- For iOS 14.3 and 14.4 use SFSafariViewController to open a web page containing an iframe with its src specified as a video call room URL.
- For iOS versions lower than 14.3. redirect to mobile Safari is recommended.
For video calls with Cordova (Phonegap), please, use the plugin for SafariViewController
Embedding using iOS/Android SDK
Beta versions of iOS and Android native SDK can be provided separately.
Meeting customization
URL Attributes for rich customization
Meeting customization is achieved with optional URL parameters for each iframe instance.
It’s possible for each participant in a meeting to have different parameter combinations.
&accessToken=<token> |
Set a one-time access token |
JWT, URL |
&accessUrl=<url> |
Set your server-based authorization method for checking access token |
JWT, URL |
&apiEvent=<url> |
Set webhooks server-based method for receiving server events |
JWT, URL |
&authEvent=<header> |
Set specific webhooks http request header for receiving server events |
JWT, URL |
&authorizationAccess=<header> |
Set specific http request header for checking access token |
JWT, URL |
&autoplayWithoutAudioTrack=<true|false> |
Sets a flag don’t ask mic permission on iOS devices for webinar viewer |
URL |
&canRecord=<true|false> |
Allow to activate the recording function for the moderator |
JWT only |
&controlsDisabled=<true|false> |
Hide main UI controls and buttons |
URL |
&disableChat=<true|false> |
Disable text chat |
URL |
&displayName=<name> |
Set display name of participant |
JWT, URL |
&itisparticipant=<true|false> |
Set mode of a viewer or a participant in webinars |
JWT, URL |
&lang=<code> |
Set the interface language explicitly |
URL |
&minimizeTiles=<true|false> |
Increase the number of simultaneously displayed tiles of participants on the screen without scrolling to the maximum |
URL |
&nameScreenDisabled=<true|false> |
Skip welcome page with a cam/mic selection and a name input |
URL |
&peerId=<id> |
ID of a participant from your internal system |
JWT, URL |
&role=<role> |
Set privilege role for a participant |
JWT only |
&sortPeers=<true|false> |
Move participants with cameras up to the visible area |
URL |
&startWithFS=<true|false> |
Start meeting in full screen mode |
URL |
&token=<jwt> |
Set JWT token |
JWT, URL |
&tokenLifetime=<milliseconds> |
Lifetime of JWT token |
JWT, URL |
&video=<url> |
Display an external HTML player with external video broadcasting for joint viewing |
JWT, URL |
&waitingRoom=<true|false> |
Activate waiting room |
JWT only |
Examples of use:
1. https://meet.gcorelabs.com/call/?roomId=serv0testroom&displayName=John%20Snow
2. https://meet.gcorelabs.com/call/?roomId=serv0testroom&displayName=John%20Snow&disableChat=true
3. https://meet.gcorelabs.com/call/?roomId=serv0testroom&displayName=John%20Snow&disableChat=true&lang=en
Attributes details
1. &accessToken=<token>
Type: String. default = not set.
Security access token generated on your side. If this parameter is specified, when the user enters the room, our server will additionally ask your authorization server whether it is possible for the user with the peerID and accessToken parameters to enter the room. See the server-side authorization method for details.
Example:
&accessToken=802380f4-dd70-4d60-9738-fb5ae8709ae7
2. &autoplayWithoutAudioTrack=<true|false>
Type: Boolean, default = false.
It is used only for iOS devices and for webinars.
iOS Safari browser policy requires microphone permission for using audio with WebRTC.
A browser asks a passive viewer (no cam/mic buttons) in a webinar room to allow mic using. This parameter tries not to ask for microphone permission, but to play audio calling the simple “play” method.
Example:
&autoplayWithoutAudioTrack=true
3. &canRecord=<true|false>
Type: Boolean, default = false.
Despite not everyone needs a recording for security reasons, legal restrictions, or storage space usage, room activities can be recorded and saved in the Cloud.
Recording can be activated using this attribute. If the feature is activated, the recording is turned on by the moderator using the button in its interface.
Example:
&canRecord=true
4. &controlsDisabled=<true|false>
Type: Boolean, default = false.
Hide general controls and buttons from the screen. In this case, you should use ClientAPI methods to manage actions and allow users to turn on/off their cams/mics.
Example:
&controlsDisabled=true
5. &disableChat=<true|false>
Type=Boolean, default value = false.
Disable chat function. Chat and the bottom “chat” button are not available to the participants.
Useful when you use our own chat.
Example:
&disbleChat=true
6. &displayName=<name>
Type: String, default value = not set.
Set the display name for a participant.
A participant’s name may be known before they join the meeting. It is possible to pass the name from your internal system and not force the user to enter it again on the welcome page.
If you specify the name in the attribute, then the user will not be able to change it through UI.
Example:
&displayName=John%20Snow
7. &itisparticipant=<true|false>
Used for webinar rooms only.
Type = Boolean, default value = false.
The parameter determines the behavior of the webinar interface where there are participants and viewers. All attendees are viewers only.
Participants are presented in the room as regular users with the ability to turn on the camera and microphone, they also have a standard participant rectangle.
Viewers can observe what is happening in the room, see and hear, but they do not have a dedicated participant rectangle and cannot turn on the camera or microphone.
Example:
&itisparticipant=true
8. &lang=<code>
Type: String, default = not set.
Set the meeting UI language to match your product or service. In general UI language is based on the participant browser's language settings.
This parameter is set in the browser settings by the user himself and then transmitted by the browser in the Accept-Language parameter of the HTTP request (https://www.w3.org/International/questions/qa-lang-priorities).
Select from:
- English = en
- Russian = ru
Therefore, in most cases, you do not need to specify this parameter explicitly. If the video room UI is translated and available for the user’s language, then UI will be automatically switched to it. If there is no such language, then the English version will be enabled by default.
If you need to explicitly set the language based on your internal/enterprise settings, then use it.
Example:
&lang=en
9. &minimizeTiles=<true|false>
Type: Boolean, default = false.
Make the participants' tiles small so that as many participants as possible fit on one screen without scrolling.
This parameter allows increasing the number of simultaneously displayed tiles of participants on the screen to the maximum.
Example:
&minimizeTiles=true
10. &nameScreenDisabled=<true|false>
Type: Boolean, default = false.
Skip the welcome page with a name input field and cam/mic selection.
You can skip the cam/mic selection elements if the user's devices are known or you need to immediately connect the user inside the room.
In this case, you should specify the user’s name in the attribute and use ClientAPI for the Join method. Please, see the Join method.
Example:
&nameScreenDisabled=true
11. &peerId=<id>
Type = String, default value = set by the video server with a random GUID value.
Use a participant identifier attribute if you want to set participant ID explicitly. Get data from your database or enterprise services.
Value can be any you prefer: number, GUID, or email.
Please, note! The unique identifier can be used in only one simultaneous session.
When several participants with the same peerID try to connect a session will be created only with the most recent one, and all others will be terminated.
The same is true when a link is opened in different browsers: a new session will be created only with the most recent browser, and all previous ones will be terminated.
Example:
- User1 opens a link with &peerID=5 and then User2 opens the same link with &peerID=5. The second user will log in, but the server connection with the first user will be closed and the User1 will not be able to participate. Thus, need to use two different peerIDs.
- A User opens a link with &peerID=5 on a desktop computer and then opens the same link on a mobile device. He will log in on the mobile device, but the server connection with the desktop computer will be closed.
peerID is used for:
- ClientAPI methods when you want to apply a method for a specific user.
- Download statistics on the attendance of the video call room and the duration of the user's presence on the call.
Example:
&peerId=802380f4-dd70-4d60-9738-fb5ae8709ae7
12. &role=<role>
Type: String, default = not set.
Set privilege role for a participant.
Values:
- [Not set] – regular participant.
- Moderator – super-user who can manage participants and video call settings.
By default, all attendees are common participants. They able to manage their own cams and mics. But moderator is able to manage participants, turn off cams/mics, allow them to enter.
You can give the organizer the role of moderator.
Example:
&role=moderator
13. &sortPeers=<true|false>
Type=Boolean, default value = false.
Use the attribute to sort participants' tiles. Those with video are displayed on top.
By default, the participants' tiles are arranged in the order of their connection to a meeting room.
This order does not change during a meeting.
For example, if first many users connect without video, and then at the end a participant with a camera connected, then he can stay at the bottom under scrolling (visible area) of the screen and no one will see him.
The attribute allows you to show active participants with video.
Please, note! Enabling this option increases the load on the participant's CPU.
Example:
&sortPeers=true
14. &startWithFS=<true|false>
Type: Boolean, default = false.
Start meeting room in Full Screen mode.
Example:
&startWithFS=true
15. &token=<jwt>
Type=String, default value = not set.
JSON Web Tokens is an open, standard method for representing claims securely between two parties https://jwt.io/
JWT allows you:
- To specify attributes inside a token, instead of URL attributes.
- Sign a token with a secret key and be sure that all parameters in it are specified by your side, and not changed by someone else.
Please, see Security for details.
Example:
&token= eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoibW9kZXJhdG9yIiwic3RhcnRUaW1lIjoiMjAyMS0wNi0yMVQwMDowMDowMC4wWiJ9.Atj-TPL_GSLyuI565pI6X_6GFjopXf62C6y4OgeeEk9KEb_1cosDmo2sytpBv44PRuMRwgDg8AcqlMMgA0kcdJrBZ7AAywjb6RZVXlian6-6XQ0zx7OhYyDo2-mVxCO9dgYroXfz2Fw8lyNuqFl0AKEfFMPKaYf46u5kjwWmSyhh7bLbL969Eu3zW_Mk3sYLpW_xULyndhkXrLqOVspK08Mla-AbxGJ94pZXJCKHK5UslhrGJ6RProN5nL4NaXOCKRX0ffKnklxiyn9MgKf0cc6Za0GCpjg-d3y6-UOVd0AXW8TWR-RllTgXaTUMMSLyWzHPsv-e2O-GsA0WJnBJEg
16. &tokenLifetime=<milliseconds>
Type=Number, default value = not set.
The attribute limits the token lifetime. Token lifetime is set in milliseconds and is counted from the moment of the first connection. After the specified period ends, a participant cannot reconnect to the room with the token.
Example:
&tokenLifetime=60000
17. &video=<url>
Type=String, default value = not set.
The attribute helps to organize a joint viewing of online broadcasts right in the video call room.
Screen sharing with losing both video and audio quality and overloading one of the participant's computers is no needed.
Instead insert the code of Youtube, our, or any other HTML player and it will appear for all participants in the room. The player saves all its standard functions such as adaptive bitrate, counting unique viewers, displaying ads, Google Analytics counter, etc.
Please see Joint viewing feature.
Example:
https://meet.gcorelabs.com/call/?roomId=serv1testroom&displayName=John%20Snow&video=https%3A%2F%2Fwww.youtube.com%2Fembed%2FXBPjVzSoepo
18. &waitingRoom=<true|false>
Type: Boolean, default = false.
The waiting room function allows a moderator to manually determine which user is allowed to enter the video call room and who is not.
After enabling the feature each participant will see Please wait for a confirmation message.
Example:
&waitingRoom=true
Debug and Dev URL attributes
A set of debug attributes can be used by developers to create and test a video call room.
These parameters are used for debugging purposes only.
19. &accessUrl=<url>
Type=String, default value = not set.
URL of rest method to check accessToken.
Please, see Security for details.
Do not forget to use https:// instead of http://.
Please, do not use this attribute publicly. For public use, the URL should be registered on our server or in your account.
Example:
&accessUrl= https://your.domain.com/api/gcorelabs/auth
20. &apiEvent=<url>
Type=String, default value = not set.
URL of getting webhooks/events from the video server.
Do not forget to use https:// instead of http://.
Please, do not use this attribute publicly. For public use, the URL should be registered on our server or in your account.
Example:
&apiEvent=https://your.domain.com/api/gcorelabs/webhook
21. &authEvent=<header>
Type=String, default value = not set.
Extra header request parameters and credentials for server-side webhooks/events.
Use it for enabling Basic or Bearer authentication.
Please, do not use this attribute publicly. For public use, the URL should be registered on our server or in your account.
Example:
&authorizationAccess=Basic%20Z2NvcmVfbWVldDo4dFpvOTZLSkhWRXFBanFBQlpZQg%3D%3D
22. &authorizationAccess=<header>
Type=String, default value = not set.
Extra header request parameters and credentials for server-side check of authorization.
Use it for enabling Basic or Bearer authentication.
Please, do not use this attribute publicly. For public use, the URL should be registered on our server or in your account.
Example:
&authorizationAccess=Basic%20Z2NvcmVfbWVldDo4dFpvOTZLSkhWRXFBanFBQlpZQg%3D%3D
Room types for video conferencing
There are 2 room types: video conferencing and webinars.
Video conferencing rooms: all invited participants are with cameras and microphones on. There can be from 1 to 50 participants in a room.
Webinars rooms: participants are divided into groups of speakers and viewers.
Speakers are active participants with cameras and microphones on. Participants can watch and hear them. Viewers can only look at the speakers without interactive participation. They have neither a camera nor a microphone. There can be from 1 to 20 speakers and 0-2000 viewers in a room.
Video conferencing rooms
Method to create video conferencing rooms is /call/.
Example:
https://meet.gcorelabs.com/call/?roomId=
Webinars rooms
Method to create video conferencing rooms is /webinar/.
Please see also &itisparticipant=true attribute.
Example:
https://meet.gcorelabs.com/webinar/?roomId=
API Usage
Client API
Example of iframe integration
<iframe allow="camera; microphone; display-capture" style="height: 100%; width: 100%;" src="https://meet.gcorelabs.com/webinar/?roomId=qwesfder4w4&displayName=Tom&accessToken=sda3-q23aed-aerae&peerId=123123-321as-waaew-ads&apiEvent=https://example.com/api/meet&accessUrl=https://example.com/api/accessCheck/&itisparticipant=true&nameScreenDisabled=true&startWithFS=true&controlsDisabled=true"></iframe>
Please, see Embed a meeting room on web site and Attributes details.
Interaction with iFrame
There is a special library for interacting with the iframe, which should be loaded separately.
<script type="text/javascript" charset="utf-8" src="https://meet.gcorelabs.com/meetBridgeApi.js"></script>
JavaScript method for initialization:
meetIframeBridge = new MeetIframeBridge.default({ element: $iframe.get(0), roomId: "serv1m6oci9e8" });
Where:
- element – DOM object of the iFrame.
- roomId - ID of the room.
Please, note! Before initializing the class, you need to wait for the iframe element to be loaded.
Public methods of Meet’s iFrame
Client API methods allow you to control the video room, perform actions with hidden main controls, react to what is happening inside the room.
Example of method execution:
Initializing:
var meetIframeBridge;
$('#meetframe').on("load", function() {
meetIframeBridge = new MeetIframeBridge.default({ element: $("#meetframe")[0], roomId: "serv1m6oci9e8" });
});
Joining:
meetIframeBridge.method({ name: "join", data: {constraints: {video: false, audio: false }}, callback: (e) => { alert(1); return true; } });
Volume adjusting:
meetIframeBridge.method({ name: "setVolume", data: 100, callback: (e) => { alert(1); return true; } });
Name changing:
meetIframeBridge.method({ name: "changeDisplayName", data: "Tom", callback: (e) => { // return value } });
Getting screenshot of a user’s video:
meetIframeBridge.method({ name: "getScreenshotByPeerId", data: "id", callback: (e) => { // “e” parameter will have screenshot data } });
Method name |
Parameters |
Description |
join |
“constraints” = object
Setup new devices: data: {constraints: { video: { deviceId: 'id', label: 'label', groupId: 'groupId', kind: 'video'}, audio: { deviceId: 'deviceId', label: 'label', groupId: 'groupId', kind: 'audio'}}}
If you want to use devices by default: data: {constraints: {video: true, audio: true }}
|
Join method receives a stream from these devices (usually used with the nameScreenDisabled parameter) |
enableMic |
Turn on the microphone |
|
disableMic |
Mute the microphone |
|
enableWebcam |
Turn on the camera |
|
disableWebcam |
Turn off the camera |
|
enableShare |
Enable screen sharing |
|
disableShare |
Turn off screen sharing |
|
changeDisplayName |
“name” data: string |
Change a name |
setVolume |
“volume” data: number |
Set a volume level (0 - 100) |
getScreenshotByPeerId |
“peerId” data: string |
Get a screenshot of a user with an id equal to peerId, the screenshot is given in Base64 |
setControlsVisible |
“visible” data: bool |
Show and hide controls |
isCameraEnabled |
is the user's camera enabled |
|
isMicroEnabled |
is the user's microphone enabled |
|
isShareEnabled |
is the user's sharing enabled |
|
changeDevice |
“constraints” = object data: {constraints: { audio: { deviceId: 'deviceId', label: 'label', groupId: 'groupId', kind: 'audio'}}}
or
data: {constraints: { video: { deviceId: 'id', label: 'label', groupId: 'groupId', kind: 'video'}}} |
Change a device on the fly. Specify one device per method call. |
playAudio |
Start audio that could not be played (usually used in conjunction with autoplayWithoutAudioTrack) |
|
muteAudio |
Mute incoming audio |
|
unmuteAudio |
Unmute incoming audio |
|
setBitrate |
“bitrateValue” data: number |
Sets the maximum video bitrate in the room |
isFullscreenEnabled |
Is fullscreen enabled |
|
enableFullscreen |
Turn on fullscreen |
|
disableFullscreen |
Turn off fullscreen |
|
enablePin |
“peerId, data: string |
Enable pin for a specified user |
disablePin |
Disable pin |
|
setLocale |
“locale” data: string |
Dynamic language changes, available languages: en, ru |
disabledTrackByModerator |
“peerId”, “kind = (audio || video)” data: {userPeerId: 'peerId', kind: 'audio'} |
Turn off video or audio from another user in a moderator mode. Only a moderator can disable video and audio |
disableAllMics |
|
Mute mics of all participants, can be used only by a moderator |
disableAllCameras |
|
Turn off cams of all participants, can be used only by a moderator |
Events from an iframe
Events on the client side allow you to react quickly to actions/exceptions inside a video room.
Example of event subscription:
meetIframeBridge.on('switchOnCamera', (e) => { your code here });
Event name |
Data |
Description |
join |
peerId, displayName |
A user is added to the room |
switchOnCamera |
peerId, displayName |
Camera is on |
switchOffCamera |
peerId, displayName |
Camera off |
errorGetCamera |
peerId, displayName |
Camera connection error |
switchOnMic |
peerId, displayName |
Microphone is on |
switchOffMic |
peerId, displayName |
Microphone off |
errorGetMic |
peerId, displayName |
Microphone connection error |
switchOnShare |
peerId, displayName |
Screen sharing enabled |
switchOffShare |
peerId, displayName |
Screen sharing is off |
errorGetShare |
peerId, displayName |
Screen sharing error |
newPeer |
peerId, displayName |
New user comes |
peerClosed |
peerId, displayName |
A user left the room |
connectionFailed |
The server connection is broken |
|
disconnected |
The server connection is closed (example: the server is unavailable) |
|
connectionClosed |
A user has closed the server connection |
|
connectionError |
peerId, error message |
The error message: error happened on a client or a server side |
playingAudioPrevent |
It is impossible to play audio without clicking (used in conjunction with the autoplayWithoutAudioTrack parameter) |
|
switchOnPin |
peerId |
Pin function is on |
switchOffPin |
Pin function is off |
|
errorGetPin |
peerId |
pin feature error |
Server API, endpoints
Video Conferencing Endpoints
Please see REST API specification. Below is brief list of endpoints.
Request example: https://webrtc1.youstreamer.com:443/<roomId>/closeRoom
Method name |
Parameters |
Description |
/rooms/:roomId/closePeer |
peerId, body:{peerId: id} |
Remove a user from a room, POST |
/rooms/:roomId/durationOfBroadcast |
How long the room existed, GET |
|
/rooms/:roomId/closeRoom |
Delete a room, GET |
|
/rooms/:roomId/numberPeers |
The number of participants in the room, GET |
|
/rooms/:roomId/existingPeer |
peerId, body:{peerId: id} |
Does the user exist in the room or not |
Example of a video server performance check
Call method like https://webrtc2.youstreamer.com/rooms/serv1l8bsg8zw1/durationOfBroadcast
For a non-existent room, the answer is 400.
If it is error 500 or falls off on timeout, then the server is unavailable.
List of servers for calling video conferencing endpoints
We have a lot of servers over the world. Some of them are for public usage.
The server name is derived from the roomID.
For example: &roomId = serv1qweqwe.
Server |
Country |
Server URL |
Description |
serv1 |
Russia |
https://webrtc2.youstreamer.com:443 |
|
serv2 |
Luxembourg |
https://webrtc3.youstreamer.com:443 |
|
serv3 |
Australia |
https://webrtc4.youstreamer.com:443 |
|
serv4 |
USA |
https://webrtc5.youstreamer.com:443 |
|
Please, note! There is an offset of +1 in the server’s url. This is a temporary but necessary solution and will be changed soon. We will inform you additionally.
For debugging purposes, you are able to call the server endpoint directly.
For public use, we apply strong restrictions and increase the level of security. Please write us, from which servers and with what security parameters server-calls will be allowed, all other calls will be rejected.
Server events and webhook methods
All events from the server are pushed to the URL specified in the apiEvent attribute:
Event name |
Parameters |
Description |
joinPeer |
roomId, peerId, displayName |
A new user has connected |
closePeer |
roomId, peerId, displayName |
A user has disconnected |
Webhook joinPeer
Method of notifying that a participant has joined a room.
This method is used for extra authorization checking on your side.
GET /joinPeer
Attributes:
- roomId
- peerId
- displayName
- token
Output codes we await from your side:
- 200 OK – Participant is allowed to join the room.
- 401 Unauthorized – Participant is not allowed to join the room, access is declined.
- 423 Locked – Access is closed temporarily for locked rooms. When you close or limit the maximum number of participants.
* It is intended to display a human-readable message about the reasons and contacts for the moderator, instead of simple access denied message.
- 425 Too Early – Access is closed temporarily for those events that have not yet started.
*It is intended to display a human-readable The event has not started yet. Start % d% message. Start time is taken from a token.
Webhook closePeer
Method of notifying that connection between the server and the participant’s browser has been closed.
In most cases, this means that the participant has left the room by himself or there was a problem with the Internet connection.
GET /closePeer
Attributes:
- roomId
- peerId
- displayName
- token
Output codes we await from your side:
- 200 OK.
Video Platform Endpoints
Video conferencing tool manages data in real-time.
Server API and Client API of video conferencing are designed to control the behavior of users and video rooms in real-time.
Statistics of usage and video records are stored in the Streaming Platform.
Please, use Video Platform’s REST API for those methods – https://apidocs.gcorelabs.com/streaming
To access Video Platform API you need to be authenticated. The majority of methods require an API token in the Authorization header.
An API token is a unique key that all users and applications should add to requests to interact with our services.
Please authenticate via https://apidocs.gcorelabs.com/streaming#section/Authentication
There will be new methods described later: RECORD ROOM.
Usage Statistics
Video conferencing tool sends data of usage every 30 seconds to the Video Platform servers. This means that the usage statistics are always a multiple of 30 seconds.
Common usage data of room:
The aggregated data for the room in summary.
GET /vp/api/statistics/peers/summary
Attributes:
- room_id
- from – start period of selecting data
- to – finish period of selecting data
Output codes:
- 200 – OK, json object with the data.
- 400 – Bad Request, in case of incorrect input attribute values.
- 403 – Unauthorized access.
- 404 – Not found, in case there is no data for room or room is not found in statistics.
- 500 – Internal error.
Output values:
- participants – the total sum of unique participants in the room.
- start_time – unix time in seconds of the first entry time of the first participant, e.g = 1624276920.
- end_time – unix time in seconds of the very last participant leaving, e.g = 1624358940
- duration – room activity seconds, calculated as the difference between the end _time parameter value and the start_time parameter value. e.g = 90660
Please note, the result is contained aggregated data for all sessions of the specified room between “from” period till “to” period.
If you use the same room ID each day, then separate periods.
For example, https://meet.gcorelabs.com/call/?roomId=serv1test1 used for 60 minutes each day on Monday, Jun 21, and on Tuesday, Jun 22.
- /summary?from=2021-06-21T00:00:00.0Z&to=2021-06-21T23:59:59.99Z&room_id=serv1test1 – will return 60 minutes (60 mins on Jun 21).
- /summary?from=2021-06-21T00:00:00.0Z&to=2021-06-22T23:59:59.99Z&room_id=serv1test1 – will return 120 minutes (60 mins on Jun 21 + 60 mins on Jun 22).
Usage Example:
https://api.gcdn.co/vp/api/statistics/peers/?from=2021-06-21T00:00:00.0Z&to=2021-06-22T23:59:59.99Z&room_id=serv1test2a
Example of return data:
{
"data": {
"participants": 3,
"start_time": 1624268280,
"end_time": 1624358940,
"duration": 90660
},
"errors": []
}
Details of usage data per participant
The data for each participant’s sessions for a room.
If the event lasted 60 minutes, and the user entered for the first 5 minutes, then left the room, and joined again for the last 5 minutes, then the statistics will reflect 2 sessions by 5min + 5min = 10 minutes (that is, = 600 seconds, instead of 3600 seconds of the total duration).
GET /vp/api/statistics/peers/
Attributes:
- room_id
- from
- to
Output codes:
- 200 – OK, json object with the data.
- 400 – Bad Request, in case of incorrect input attribute values.
- 403 – Unauthorized access.
- 404 – Not found, in case there is no data for room or room is not found in statistics.
- 500 – Internal error.
Output values:
- an array of participant sessions
- person_id – peerId data (your value if it is specified in URL attributes, or unique GUID made automatically if it is omitted)
- join_time – unix time in seconds of participant’s entry time, e.g = 1624268280
- leave_time – unix time in seconds of participants leave time, e.g = 1624269300
- duration – session duration in seconds, e.g = 1260
Example of usage:
https://api.gcdn.co/vp/api/statistics/peers/summary?from=2021-06-21T00:00:00.0Z&to=2021-06-22T23:59:59.99Z&room_id=serv1test2a
Example of return data:
{
"data": [
{
"person_id": "peer2",
"join_time": 1624268640,
"leave_time": 1624269300,
"duration": 660
},
{
"person_id": "peer1",
"join_time": 1624270800,
"leave_time": 1624274520,
"duration": 3720
},
{
"person_id": "peer3",
"join_time": 1624269180,
"leave_time": 1624269300,
"duration": 120
},
{
"person_id": "peer1",
"join_time": 1624358460,
"leave_time": 1624359240,
"duration": 780
},
{
"person_id": "peer1",
"join_time": 1624270380,
"leave_time": 1624270740,
"duration": 360
},
{
"person_id": "peer1",
"join_time": 1624268280,
"leave_time": 1624269300,
"duration": 1020
},
{
"person_id": "peer3",
"join_time": 1624268640,
"leave_time": 1624269180,
"duration": 540
}
],
"errors": []
}
Record Room
[TBD]
Security
Allowed domains
For embedded in an iframe meetings to work inside a website, its domain has to be allowed.
The list of allowed domains can be updated from the account.
Please, note! Domains should be prefixed with https:// and have no path.
Wildcards to allow all subdomains under a domain are permitted, for example, https://*.domain.com.
Rooms domain names
Video calls are accessible on special domains:
- companyname.gvideo.co – the example of client's special domain in our zone "gvideo.co"
- video.domain.com – the example of external client's domain
We provide you a third-level domain in the gvideo.co zone by default. If you prefer to use your own domain, please contact us.
JWT & Secret Key
JWT allows you to accurately determine the validity of the video room settings and unambiguously determine the belonging of the token to your account.
To use JWT you need a Public & Secret Key. A new key is generated by you.
Send us your public part of the key in the Account section in the Video conferencing dashboard.
Please, see RSA Public & Secret Key generation section below for details.
You can activate an option to use JWT in your account. If you activate this option, it will be necessary to send JWT &token=xxx in every request.
Without specifying the token, the Access denied message will be displayed on the screen.
If you activate JWT token usage, you will not be able to use the attribute &accessToken=xxx.
JWT Usage
We use the RS256 algorithm for signing and generating the hash.
RS256 refers to the SHA256 hash function.
RFC states https://tools.ietf.org/html/rfc7518#page-8
"alg" Param Value | Digital Signature Algorithm |
RS256 | RSASSA-PKCS1-v1_5 using SHA-256 |
And there is RSA key of size 2048 or larger bits that should be used with this algorithm.
The RSASSA-PKCS1-v1_5 SHA-256 digital signature is generated as follows: generate a digital signature of the JWS Signing Input using RSASSA-PKCS1-v1_5-SIGN and the SHA-256 hash function with the desired private key. This is the JWS Signature value.
Please, see RSA Public & Secret Key generation section below for details.
Please, use https://jwt.io/ to verify your JWT tokens.
JWT Parameters
JWT contains header and payload (body) parts.
The header of JWT is regulated to use the following parameters:
HEADER:ALGORITHM & TOKEN TYPE
{
"typ": "JWT",
"alg": "RS256"
}
JWT body contains important data that should be signed and verified.
The data inside the JWT has more priority than the values of the same parameters specified in the URL attributes. This means that if an attribute value is simultaneously specified both inside the JWT and in the URL attributes set, then the value from the JWT will be used.
Please, see the list of parameters that can be put inside JWT in the table of attributes above.
Priority of usage inside JWT and from URL:
- Parameters with the JWT label can be specified inside a token or as an attribute in the URL. If the attribute value is specified in the token, then the value in the URL is ignored. If the attribute is not specified in the token, then the attribute value will be taken from the URL.
- Parameters with the URL label can only be specified as an attribute in the URL.
Extra list of attributes for JWT usage:
- startTime – planned start time of the event in a video room. Please, see Webhook joinPeer method.
The list of attributes is expanding, tell us what attributes (from the general list of URL attributes) you need inside the token.
PAYLOAD:DATA
{
"roomId": "abcd1234",
"role": "moderator",
"startTime": "2021-06-21T00:00:00.0Z "
}
Example:
https://meet.gcorelabs.com/call/?roomId=YOUR_ROOM_ID&token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoibW9kZXJhdG9yIiwic3RhcnRUaW1lIjoiMjAyMS0wNi0yMVQwMDowMDowMC4wWiJ9.Atj-TPL_GSLyuI565pI6X_6GFjopXf62C6y4OgeeEk9KEb_1cosDmo2sytpBv44PRuMRwgDg8AcqlMMgA0kcdJrBZ7AAywjb6RZVXlian6-6XQ0zx7OhYyDo2-mVxCO9dgYroXfz2Fw8lyNuqFl0AKEfFMPKaYf46u5kjwWmSyhh7bLbL969Eu3zW_Mk3sYLpW_xULyndhkXrLqOVspK08Mla-AbxGJ94pZXJCKHK5UslhrGJ6RProN5nL4NaXOCKRX0ffKnklxiyn9MgKf0cc6Za0GCpjg-d3y6-UOVd0AXW8TWR-RllTgXaTUMMSLyWzHPsv-e2O-GsA0WJnBJEg
RSA Public & Secret Key generation
Keys can be generated by any RSA keygen tool.
If you don’t know any of them, then we recommend to use the OpenSSL tool.
To perform the following actions for Windows or Linux, check and/or install OpenSSL on your system.
Commands to generate a secret key and an export public key:
- openssl genrsa -out key_name.key 2048
- openssl rsa -in key_name.key -pubout -outform PEM -out key_name.key.pub
File key_name.key.pub will contain the public part of the key. File key_name.key will contains the private part of the key.
Note. The number 2048 in the above command indicates the size of the private key.
You can choose 2048 or 4096 (these numbers represent bits).
The larger sizes offer greater security, but this is offset by a penalty in CPU performance.
We recommend the best practice size of 2048. It seems like 2048 bits is enough for the foreseeable future (2030 horizon).