Русский English (US) 简体中文

Статьи в этом разделе

Групповые видеозвонки API

Version 07/21

 

There are two video conference room integration ways:

  1. Codeless – just copy an URL, paste iframe on your page… and join a call.
  2. 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.

 

Get started

Codeless integration

Mobile apps integration

Meeting customization

API Usage

Security

 

 

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:

  1. Override the WebChromeClient.onPermissionRequest method to avoid the default implementation. You can just return true.
  2. 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:

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:

  1. openssl genrsa -out key_name.key 2048
  2. 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).

 

 

 

Похожие статьи