API видеозвонков

Последние изменения: 29.11.2022

Простой инструмент для видеоконференций.

Видеоконференции можно интегрировать на сайт двумя способами: 

  1. Без кода — скопируйте URL-адрес, вставьте iFrame на свою страницу и присоединяйтесь к звонку. 

  2. На основе API — для тонкой настройки и интеграции с вашими платформами/системами. 

Начало работ
Интеграция без кода

Интеграция с мобильными приложениями

Кастомизация видеозвонков

API клиента

API сервера

Безопасность

Решение проблем

Начало работы

Создайте встречу в браузере: 

1. Откройте https://vconf.edgecenter.ru/new.

2. Нажмите кнопку «Создать конференцию».

3. URL-адрес комнаты будет создан автоматически. 

4. Нажмите «Присоединиться». 

5. Отправьте URL-адрес (например, https://vconf.edgecenter.ru/call/?roomId=serv0testroom) другим участникам, чтобы они присоединились к видеозвонку. 

Например: 

https://vconf.edgecenter.ru/call/?roomId=serv0testroom

Вставьте комнату для видеозвонков на свой сайт или в приложение через iFrame. Атрибут src iFrame указывается как URL-адрес.

Например:

<iframe allow="camera;microphone;fullscreen;display-capture;autoplay;screen-wake-lock" src=" https://vconf.edgecenter.ru/call/?roomId=serv0testroom123"></iframe>

Вы можете настроить видеозвонок с помощью атрибутов URL.

Например:

https://vconf.edgecenter.ru/call/?roomId=serv0testroom&displayName=JohnSnow

Интеграция без кода

Создать URL комнаты

1. Создайте идентификатор комнаты. Используйте буквенно-цифровой набор символов. Например: bokxlj33

2. Добавьте местоположение сервера. Добавьте в начале «serv0» или «serv1» для сервера в России. Результат: serv0bokxlj33

3. Метод для видеовызова: /call/

4. Вставьте идентификатор комнаты в конечный URL. Результат: https://vconf.edgecenter.ru/call/?roomId=serv0bokxlj33

Вы можете создать URL-адрес, сохранить его, отправить или сохранить в качестве заметки. URL можно использовать повторно. URL-адрес будет активен все время — до события, во время события и даже через 1 год после события.

Комната создается на сервере в момент входа в нее первого участника.

Комната автоматически удаляется без сохранения информации после ухода последнего участника.

Встроить комнату на сайт

Для интеграции комнаты в сервис или приложение используйте iFrame с атрибутом src (указывается URL-адрес). Посмотрите раздел «Разрешенные доменные имена», чтобы узнать, как разрешить домен вашего сайта, чтобы браузеры не блокировали iFrame.

Настройки iFrame должны иметь специальные разрешения, необходимые для видеовызовов:

allow="camera;microphone;fullscreen;display-capture;autoplay;screen-wake-lock"

HTTP-заголовок Feature-Policy предоставляет механизм, который разрешает:

Например: 

<iframe 
src="https://vconf.edgecenter.ru/call/?roomId=serv0testroom123"
allow="camera;microphone;fullscreen;display-capture;screen-wake-lock"
></iframe>

Интеграция с мобильными приложениями

Встраивание в Android-приложения

Встроить видеозвонки в Android можно 2 способами:

1. Android Native SDK.
2. WebView.

Мы рекомендуем использовать первый способ, который поддерживает звонки один на один, а также большое количество участников для общения в режиме реального времени в своём приложении. 

Есть два модуля: 

SDK — нативная библиотека видеозвонков для внедрения в приложения. Библиотека отвечает за все внутренние процессы: получение данных с камеры/микрофона, создание видеопотоков, отправка и получение данных на/с видеосервера.

DEMO — собственное демонстрационное приложение с открытым исходным кодом. Приложение показывает кейсы и сценарии использования SDK в реальном приложении. Вы можете скомпилировать код и запустить его.

Способ WebView требует использования класса WebView. Чтобы разрешить комнате доступ к камере:

  1. Переопределите метод WebChromeClient.onPermissionRequest, чтобы избежать реализации по умолчанию. Вы можете просто установить значение true.

  2. Добавьте параметр &nameScreenDisabled=true к URL-адресу комнаты и вызовите метод клиентского API Join.

Встраивание в iOS-приложения

Встроить видеозвонки в iOS можно 2 способами:

1. iOS Native SDK.
2. WebView.

Мы рекомендуем использовать первый способ, который поддерживает звонки один на один, а также большое количество участников для общения в режиме реального времени в своём приложении.

Есть два модуля:

SDK — нативная библиотека видеозвонков для внедрения в приложения. Библиотека отвечает за все внутренние процессы: получение данных с камеры/микрофона, создание видеопотоков, отправка и получение данных на/с видеосервера.

DEMO — собственное демонстрационное приложение с открытым исходным кодом. Приложение показывает кейсы и сценарии использования SDK в реальном приложении. Вы можете скомпилировать код и запустить его.

WKWebView поддерживает интеграцию страниц, которые используют WebRTC (начиная с iOS 14.5).

Для поддержки старых версий iOS рекомендуется использовать один из следующих вариантов:

  • Для iOS 14.3 и 14.4 используйте SFSafariViewController, чтобы открыть веб-страницу, содержащую iFrame с исходным кодом c src (указывается URL-адрес комнаты).

  • Для версий iOS ниже 14.3. рекомендуется редирект на мобильную версию Safari.

Чтобы использовать видеозвонки с Cordova (Phonegap), используйте плагин SafariViewController.

Встраивание в приложения React Native

Встроить видеозвонки в React Native можно с помощью 4 модулей: 

1. iOS Wrapper — демоприложение с открытым кодом React Native.
2. Android Wrapper — демоприложение с открытым кодом React Native.
3. SDK — нативная библиотека видеозвонков для внедрения в приложения. Библиотека отвечает за все внутренние процессы: получение данных с камеры/микрофона, создание видеопотоков, отправка и получение данных на/с видеосервера.
4. DEMO — собственное демонстрационное приложение с открытым исходным кодом. Приложение показывает кейсы и сценарии использования SDK в реальном приложении. Вы можете скомпилировать код и запустить его.

Кастомизация видеозвонков

Комнаты видеозвонков

Видеоконференции — это комнаты, в которых все приглашенные участники являются активными участниками с включенными камерами и микрофонами. В одном зале может находиться от 1 до 100 и более участников.

Способ создания комнат для видеоконференций — /call/.

Например: 

https://vconf.edgecenter.ru/call/?roomId=

Комнаты вебинаров

Вебинары — это комнаты, в которых участники делятся на 2 группы: спикеры и зрители. Спикеры — активные участники с камерами и микрофонами. Видео спикеров выводится на экран комнаты. Зрители участвуют неинтерактивно: у них неактивны камеры и микрофоны. В одной комнате может быть: 1–20 спикеров, 0–2 000 зрителей.

Способ создания комнат для вебинаров — /webinar/.

См. также атрибут &itisparticipant.

Например: 

https://vconf.edgecenter.ru/webinar/?roomId= 

Разрешенные доменные имена

Видеозвонки доступны на 2 типах доменов:

  1. companyname.edgevideo.ru – пример специального домена клиента в нашей зоне «edgevideo.ru».

  2. video.domain.com – пример домена внешнего клиента.

По умолчанию мы предоставляем вам технический домен третьего уровня в зоне edgevideo.ru. Если вы предпочитаете использовать собственный домен, свяжитесь с нами в чате или по почте support@edgecenter.ru.

Дополнительные URL-атрибуты для расширенной настройки

Видеозвонки настраиваются с помощью дополнительных параметров URL для каждого iFrame. У каждого участника собрания могут быть разные комбинации параметров.

&accessToken=<token>

Установить одноразовый токен доступа

JWT, URL

&accessUrl=<url>

Установить свой серверный метод авторизации для проверки токена доступа

JWT, URL

&apiEvent=<url>

Установить серверный метод веб-перехватчиков для получения событий сервера

JWT, URL

&authEvent=<header>

Установить определенный заголовок HTTP-запроса веб-хуков для получения событий сервера

JWT, URL

&authorizationAccess=<header>

Установить конкретный заголовок HTTP-запроса для проверки токена доступа

JWT, URL

&autoplayWithoutAudioTrack=<true|false>

Устанавливает флаг не запрашивать разрешение микрофона на устройствах iOS для просмотра веб-семинаров

URL

&canRecord=<true|false>

Разрешить активировать функцию записи для модератора

JWT only

&controlsDisabled=<true|false>

Скрыть основные элементы управления и кнопки пользовательского интерфейса

URL

&disableChat=<true|false>

Отключить чат

URL

&displayName=<name>

Установить отображаемое имя участника

JWT, URL

&handEnabled=<true|false>

Активировать функцию «Поднятие рука» (голосование)

JWT, URL

&hideIndicators=<true|false>

Установить режим скрытых значков внутри плиток участников (микрофон, камера, имя участника и т. д.)

URL

&itisparticipant=<true|false>

Установить режим зрителя или участника вебинаров

JWT, URL

&lаng=<code>

Установите язык интерфейса

URL

&maxBroadcasters=<num>

Максимальное количество участников с камерой/аудиоустройствами

JWT, URL

&maxWatchers=<num>

Максимальное количество участников без камеры/аудиоустройств

JWT, URL

&minimizeTiles=<true|false>

Увеличить количество одновременно отображаемых иконок участников на экране без прокрутки до максимума

URL

&nameScreenDisabled=<true|false>

Пропустить приветственную страницу с выбором камеры/микрофона и вводом имени

URL

&peerId=<id>

ID участника из вашей внутренней системы

JWT, URL

&roomId=<id>

ID комнаты

URL

&role=<role>

Установить привилегированную роль для участника

JWT only

&sortPeers=<true|false>

Переместить участников с камерами в видимую область

URL

&startWithFS=<true|false>

Начать встречу в полноэкранном режиме

URL

&token=<jwt>

Установить JWT-токен

JWT, URL

&video=<url>

Отображение внешнего HTML-плеера с внешней видеотрансляцией для совместного просмотра

JWT, URL

&waitingRoom=<true|false>

Включить комнату ожидания

JWT only

 Пример использования:

1. https://vconf.edgecenter.ru/call/?roomId=serv0testroom&displayName=John%20Snow

2. https://vconf.edgecenter.ru/call/?roomId=serv0testroom&displayName=John%20Snow&disableChat=true

3. https://vconf.edgecenter.ru/call/?roomId=serv0testroom&displayName=John%20Snow&disableChat=true&lаng=en

 Параметры атрибутов

 &accessToken=<​​token​​>

Токен безопасности, сгенерированный на вашей стороне. Если задан этот параметр, то при подключении пользователя к видеозвонку наш сервер спросит у вашего сервера авторизации, возможен ли вход в комнату для этого пользователя с параметрами peerID и Access Token. 

Тип: String, по умолчанию не установлено.

Например: 

&accessToken=802380f4-dd70-4d60-9738-fb5ae8709ae7

 &autoplayWithoutAudioTrack=<​​truе|fаlsе​​>

Используется только для iOS-устройств и для вебинаров. 

Политика браузере iOS Safari требует разрешения микрофона для воспроизведения звука с WebRTC. 

Браузер спрашивает зрителя без включенных камеры и микрофона разрешить использование микрофона. Атрибут позволяет не запрашивать разрешение микрофона, а просто воспроизводить звук. 

Тип: Boolean, по умолчанию = false.

Например:

&autoplayWithoutAudioTrack=true

&canRecord=<​true|false​>

Несмотря на то, что не всем нужна запись по соображениям безопасности, юридическим ограничениям или использованию места для хранения, действия в комнате можно записывать и сохранять в Облаке.

Запись может быть активирована с помощью этого атрибута. Если функция активирована, запись включается модератором с помощью кнопки в его интерфейсе.

Тип: Boolean, по умолчанию = false.

Например:

&canRecord=true

&controlsDisabled=<​true|false​>

Позволяет скрыть общие элементы управления и кнопки с экрана. В этом случае вы должны использовать методы ClientAPI для управления действиями и разрешить пользователям включать/выключать свои камеры/микрофоны.

Тип: Boolean, по умолчанию = false.

Например:

&controlsDisabled=true

 &disableChat=<​true|false​>

Позволяет отключить чат. Окно и кнопка чата будут недоступны участникам видеозвонка. 

Полезно, если вы используете свой собственный чат. 

Тип: Boolean, по умолчанию = false.

Например: 

&disableChat=true

&handEnabled=<​true|false​>

Активируйте функцию «Поднять руку» для комнаты. Участники смогут нажать кнопку и, таким образом, выставить индикатор поднятой руки. Индикатор отображается в плитке участника и в списке пользователей внутри панели модератора.

Тип: Boolean, по умолчанию = false.

Например:

&handEnabled=true

&hideIndicators=<​true|false​>

Скрыть значки в плитке участников. При использовании будут скрыты имя и следующие значки участников: включение/выключение камеры, включение/выключение микрофона, отсутствие, поднятая рука и кнопка «Закрепить».

Тип: Boolean, по умолчанию = false.

&hideIndicators=true

&displayName=<​name​>

Установите отображаемое имя для участника. Имя участника может быть известно до того, как он присоединится к видеозвонку. Можно передать имя из вашей внутренней системы и не заставлять пользователя вводить его снова на странице приветствия. Если вы укажете имя в атрибуте, то пользователь не сможет изменить его через пользовательский интерфейс.

Тип: String, по умолчанию не установлено.

Например:

&displayName=John%20Snow

 &itisparticipant=<​true|false​>

Используется только для вебинаров. 

Параметр определяет поведение интерфейса вебинара, где есть участники и зрители. Все участники являются только зрителями. Участники представлены в комнате как обычные пользователи с возможностью включения камеры и микрофона, также у них есть стандартный прямоугольник участника. Зрители могут наблюдать за происходящим в комнате, видеть и слышать, но у них нет выделенного прямоугольника участника и они не могут включить камеру или микрофон.

Тип: Boolean, по умолчанию = false.

Например:

&itisparticipant=true

&lаng=<​сode​>

Тип: String, по умолчанию не установлено.

Установите язык пользовательского интерфейса собрания в соответствии с вашим продуктом или услугой. Обычно язык пользовательского интерфейса зависит от языковых настроек браузера участника.Этот параметр задается в настройках браузера самим пользователем и затем передается браузером в параметре Accept-Language HTTP-запроса (https://www.w3.org/International/questions/qa-lang-priorities).  Можно выбрать:

  • Английский = en

  • Русский = ru

  • Французский = fr

  • Немецкий = de

  • Люксембургский = lb

Поэтому в большинстве случаев явно указывать этот параметр не требуется. Если пользовательский интерфейс комнаты переведен и доступен для языка пользователя, то пользовательский интерфейс будет автоматически переключен на него. Если такого языка нет, то по умолчанию будет включена английская версия. Если вам нужно явно установить язык на основе ваших внутренних/корпоративных настроек, используйте его.

Например:

&lаng=ru

&maxBroadcasters=<​num​>

Количество активных посетителей в комнате одновременно. Это максимальное количество пользователей/посетителей с включенными камерами/микрофонами.

Когда другой пользователь хочет начать говорить (включить камеру/микрофон), но количество активных участников превышает указанное значение, то этот пользователь получит системную ошибку о невозможности включения — «Ограничение: превышено максимальное количество активных участников».

Если в URL-адресе не указано значение, любой участник может включить камеру/микрофон. Обратите внимание, что количество активных пользователей прямо пропорционально нагрузке на медиасерверы. При большом количестве активных участников сервер может перегрузиться, и тогда вновь подключившиеся пользователи увидят ошибку подключения.

Параметры maxBroadcasters и maxWatchers должны быть указаны для каждого участника в URL. См. параметр &maxWatchers.

Тип: число, по умолчанию = 0.

Например:

&maxBroadcasters=10

&maxWatchers=<​num​>

Количество одновременно присутствующих в комнате. Это максимальное количество пользователей/зрителей, которые могут находиться в комнате и быть представлены собственным прямоугольником «участник». Участники могут включить свою камеру/микрофон в любое время.

Параметры maxBroadcasters и maxWatchers должны быть указаны для каждого участника в URL. См. параметр &maxBroadcasters.

Тип: число, по умолчанию = 0.

Например:

&maxWatchers=50

&minimizeTiles=<​true|false​>

Сделайте иконки участников маленькими, чтобы как можно больше участников помещалось на один экран без прокрутки. Этот параметр позволяет максимально увеличить количество одновременно отображаемых иконок участников на экране.

Тип: Boolean, по умолчанию = false.

Например:

&minimizeTiles=true

&nameScreenDisabled=<​true|false​>

Позволяет пропустить страницу приветствия с полем ввода имени и выбором камеры/микрофона. Вы можете пропустить элементы выбора камеры/микрофона, если устройства пользователя известны или вам нужно немедленно подключить пользователя внутри комнаты. В этом случае следует указать имя пользователя в атрибуте и использовать ClientAPI для метода Join. Подробнее в таблице (метод Join). 

Тип: Boolean, по умолчанию = false.

Например:

&nameScreenDisabled=true

&peerId=<​id​>

Используйте атрибут идентификатора участника, если вы хотите явно указать идентификатор участника. Получите данные из вашей базы данных или корпоративных служб. Значение может быть любым, которое вы предпочитаете: номер, GUID или адрес электронной почты. 

Обратите внимание! Уникальный идентификатор можно использовать только в одном сеансе одновременно. Когда несколько участников с одним и тем же peerID пытаются подключиться, сеанс будет создан только с самым последним, а все остальные будут прерваны. То же самое и при открытии ссылки в разных браузерах: новая сессия будет создана только с самым последним браузером, а все предыдущие будут завершены.

Пример:

  • Пользователь 1 открывает ссылку с &peerID=5, а затем пользователь 2 открывает ту же ссылку с &peerID=5. Второй пользователь войдет в систему, но соединение с сервером первого пользователя будет закрыто, и Пользователь 1 не сможет участвовать. Таким образом, необходимо использовать два разных peerID.

  • Пользователь открывает ссылку с &peerID=5 на настольном компьютере, а затем открывает ту же ссылку на мобильном устройстве. Он войдет в систему на мобильном устройстве, но соединение сервера с настольным компьютером будет закрыто.

PeerID используется для:

- Методов ClientAPI, если вы хотите применить метод для конкретного пользователя.- Скачивания статистику посещаемости переговорной комнаты и продолжительности присутствия пользователя на звонке.

Тип: String, по умолчанию устанавливается видеосервером со случайным значением GUID

Например:

&peerId=802380f4-dd70-4d60-9738-fb5ae8709ae7

&role=<​role​>

Позволяет установить привилегированную роль для участника. 

Значения:

  • [Не установлено] – обычный участник.

  • Модератор — суперпользователь, который может управлять участниками и настройками видеовстречи.

  • Переводчик — специальная роль (бета-тест) для перевода с одного языка на другой; для роли создаётся отдельный аудиоканал. Будьте внимательны: пользователи в роли «Переводчик» не могут включить камеру. 

По умолчанию все посетители являются обычными участниками. Они могут управлять своими камерами и микрофонами. Но модератор может управлять участниками, отключать камеры/микрофоны, разрешать им вход. Вы можете дать организатору роль модератора.

Тип: String, по умолчанию не установлено.

Например:

&role=moderator

&roomId=<​​id​​>

Идентификатор комнаты устанавливается вами самостоятельно в соответствии с вашими правилами. Вам не нужно вызывать какие-либо специальные методы, которые могут ограничить вас в именовании комнат.

Идентификатор состоит из двух частей «id сервера» + «id комнаты». Идентификатор сервера — «servN», см. Список серверов. Идентификатор комнаты — это любой буквенно-цифровой набор символов. Если сервер не указан, то вас подключат к дефолтному. Если указано явно — к конкретному.

&roomId определяет номер комнаты, а префиксы /call/ или /webinar/ служат модификаторами интерфейса. Например, «/call/?RoomId=testroom» и «/webinar/?RoomId=testroom» ведут в одну и ту же комнату с разным интерфейсом.

Тип: String, по умолчанию = обязательное поле, которое должно быть указано явно.

Например: 

&roomId=1111 
&roomId=bokxlj33 
&roomId=serv022222 
&roomId=serv0bokxlj33 
&roomId=serv0f53c1aa5-1492-4964-b4fe-f83b5b545e8d

&sortPeers=<​true|false​>

Используйте атрибут для сортировки иконок участников. Те, у кого есть видео, отображаются сверху. По умолчанию плитки участников располагаются в порядке их подключения к переговорной. Этот порядок не меняется во время собрания. Например, если сначала подключится много пользователей без видео, а потом в конце участник с подключенной камерой, то он может остаться внизу под прокруткой (видимой областью) экрана и его никто не увидит. Атрибут позволяет показывать активных участников с видео.

Обратите внимание! Включение этой опции увеличивает нагрузку на CPU участника.

Тип: Boolean, по умолчанию = false.

Например:

&sortPeers=true 

&startWithFS=<​true|false​>

Позволяет начать видеозвонок в полноэкранном режиме. 

Тип: Boolean, по умолчанию = false.

Например: 

&startWithFS=true

&token=<​jwt​>

Тип: String, по умолчанию не установлено.

JSON Web Tokens — это открытый стандартный метод безопасного представления претензий между двумя сторонами https://jwt.io/ JWT позволяет:

  • указать атрибуты внутри токена вместо атрибутов URL.

  • подписать токен секретным ключом и убедиться, что все параметры в нем указаны именно с вашей стороны, а не изменены кем-то другим.

Подробнее см. в разделе «Безопасность».

Например: 

&token= eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoibW9kZXJhdG9yIiwic3RhcnRUaW1lIjoiMjAyMS0wNi0yMVQwMDowMDowMC4wWiJ9.Atj-TPL_GSLyuI565pI6X_6GFjopXf62C6y4OgeeEk9KEb_1cosDmo2sytpBv44PRuMRwgDg8AcqlMMgA0kcdJrBZ7AAywjb6RZVXlian6-6XQ0zx7OhYyDo2-mVxCO9dgYroXfz2Fw8lyNuqFl0AKEfFMPKaYf46u5kjwWmSyhh7bLbL969Eu3zW_Mk3sYLpW_xULyndhkXrLqOVspK08Mla-AbxGJ94pZXJCKHK5UslhrGJ6RProN5nL4NaXOCKRX0ffKnklxiyn9MgKf0cc6Za0GCpjg-d3y6-UOVd0AXW8TWR-RllTgXaTUMMSLyWzHPsv-e2O-GsA0WJnBJEg

&tokenLifetime=<​milliseconds​>

Атрибут ограничивает время жизни токена. Время жизни токена задается в миллисекундах и отсчитывается с момента первого подключения. По истечении указанного периода участник не может повторно подключиться к комнате с токеном.

Тип: число, по умолчанию не установлено.

Например:

&tokenLifetime=60000

&video=<​url​>

Атрибут помогает организовать совместный просмотр онлайн-трансляций прямо в комнате видеозвонка. Демонстрация экрана с потерей качества видео и звука и перегрузкой одного из компьютеров участника не потребуется. Вместо этого вставьте код YouTube, нашего или любого другого HTML-плеера, и он появится у всех участников комнаты. Плеер сохраняет все свои стандартные функции такие, как адаптивный битрейт, подсчет уникальных зрителей, показ рекламы, счетчик Google Analytics и т. д.

Тип: String, по умолчанию не установлено.

Например:

https://vconf.edgecenter.ru/call/?roomId=serv0testroom&displayName=JohnSnow&video=https%3A%2F%2Fwww.youtube.com%2Fembed%2FXBPjVzSoepo 

&waitingRoom=<​​true|false​​>

Функция  ожидания позволяет модератору вручную определять, кому разрешен вход в комнату видеозвонка, а кому нет. После включения функции каждый участник увидит надпись «Пожалуйста, дождитесь подтверждающего сообщения».

Тип: Boolean, по умолчанию = false.

Например:

&waitingRoom=true

URL-атрибуты для отладки и разработки

Набор атрибутов отладки может использоваться разработчиками для создания и тестирования комнаты для видеозвонков. Эти параметры используются только в целях отладки.

&accessUrl=<​url​>

URL-адрес метода REST для проверки accessToken. Подробнее см. в разделе «Безопасность». Не забудьте использовать https:// вместо http://.

Пожалуйста, не используйте этот атрибут публично. Для публичного использования URL-адрес должен быть зарегистрирован на нашем сервере или в вашей учетной записи.

Тип: String, по умолчанию не установлено.

Например:

&accessUrl= https://your.domain.com/api/edgecenter/auth 

&apiEvent=<​url​>

URL получения вебхуков/событий от видеосервера. Не забудьте использовать https:// вместо http://.

Пожалуйста, не используйте этот атрибут публично. Для публичного использования URL-адрес должен быть зарегистрирован на нашем сервере или в вашей учетной записи.

Тип: String, по умолчанию не установлено.

Например:

&apiEvent=https://your.domain.com/api/edgecenter/webhook 

&authEvent=<​header​>

Дополнительные параметры запроса заголовка и учетные данные для веб-перехватчиков/событий на стороне сервера. Используйте его для включения аутентификации Basic или Bearer.

Пожалуйста, не используйте этот атрибут публично. Для публичного использования URL-адрес должен быть зарегистрирован на нашем сервере или в вашей учетной записи.

Тип: String, по умолчанию не установлено.

Например:

&authorizationAccess=Basic%20Z2NvcmVfbWVldDo4dFpvOTZLSkhWRXFBanFBQlpZQg%3D%3D

&authorizationAccess=<​header​>

Дополнительные параметры запроса заголовка и учетные данные для проверки авторизации на стороне сервера. Используйте его для включения аутентификации Basic или Bearer. Пожалуйста, не используйте этот атрибут публично. Для публичного использования URL-адрес должен быть зарегистрирован на нашем сервере или в вашей учетной записи.

Тип: String, по умолчанию не установлено.

Например:

&authorizationAccess=Basic%20Z2NvcmVfbWVldDo4dFpvOTZLSkhWRXFBanFBQlpZQg%3D%3D  

Модератор

По умолчанию все участники являются обычными участниками. Они могут управлять своими камерами и микрофонами. 

Модератор обладает расширенными правами. Он может управлять участниками, отключать камеры/микрофоны, разрешать вход и т. д. 

Возможности, разрешенные для модераторов: 

1. Управление функцией «Зал ожидания»: 

  • Активировать и деактивировать зал ожидания. 

  • Подтвердить и отклонить участника 

2. Управление камерами и микрофонами участников: 

  • Разрешить или запретить использование камер и микрофонов.

  • Запросить включение камер и микрофонов участников. 

3. Использование функции совместного доступа к экрану: 

  • Разрешить или запретить использование общего доступа к экрану. 

  • Запросить включение общего доступа к экрану. 

4. Работа с функцией «Поднять руку». 

  • Отменить голос участника. 

5. Работа со списком участников: 

  • Выгнать пользователя из комнаты. 

Чтобы использовать режим модератора:

1. Получите секретный ключ для JWT. См. раздел «Безопасность». 

2. Сгенерируйте ссылку для обычных участников с параметром &roomId=XXX. 

3. Создайте токен JWT. Добавьте в него дополнительный атрибут &role=moderator. 

4. Создайте ссылку для модераторов. Присоедините токен JWT с шага №3 к общей ссылке с шага №2. 

Например, ссылка для обычного пользователя:

https://vconf.edgecenter.ru/call/?roomId=serv0_test1

Ссылка для модератора: 

https://vconf.edgecenter.ru/call/?roomId=serv0_test1&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoibW9kZXJhdG9yIiwid2FpdGluZ1Jvb20iOnRydWUsImhhbmRFbmFibGVkIjp0cnVlfQ.DO_JHMDfK2mi5rycIepLVxDVs0qcQAXAhHvI7hcOIjw

Где JWT это: 

  • HEADER: (ALGORITHM & TOKEN TYPE)

  • { "alg": "HS256", "typ": "JWT" }

  • PAYLOAD: (DATA)

  • { "role": "moderator", "waitingRoom": true, "handEnabled": true, "roomId": "serv0_test1" }

Опция «Запись»

Что можно записать

Запись — опция, которая позволяет записывать интерфейса комнаты для видеовызовов таким, каким его видят обычные участники. Видео содержит: 

- участников, 
- демонстрацию экрана, 
- аудио спикеров. 

Запись — это комплексный процесс, который выполняет наша профессиональная Стриминговая платформа. Видео записывается на облачный сервер, а также хранится в облаке Стриминговой платформы. 

 Когда видезвонок закончен и видео записано, оно автоматичсеи конвертируется и становится доступно для просмотра в видеоплеере. Вы можете сохранить видео, скопировать код видеоплеера для просмотра на сайте или получить видеопоток (HLS) и вставить манифест (формат .m3u8) в мобильное приложение. 

Запись может начать только оператор.

Чтобы записать видеозвонок: 
1. Сгенерируйте JWT-токен с дополнительным атрибутом role=moderator.
2. Добавьте атрибут canRecord=true.
3. Перейдите по ссылке на команту. 
4. Откройте панель модератора внутри команты. 
5. Нажмите кнопку «Запись».
6. Нажмите «Стоп», когда завершится видеозвонок или та часть, которую вы хотите записать.

Пример JWT:

PAYLOAD: (DATA) 

{ "role": "moderator", "canRecord": true, "roomId": "serv0_test1" }

Автозапись

По умолчанию модератор может записывать встречи вручную. 

Если вы хотите записывать все комнаты автоматически, обратитесь в техническую поддержку, чтобы для вашего аккаунта активировали опцию «Автозапись».

  • Запись будет начинаться автоматически для каждой новой комнаты через ±60 секунд после подключения первого пользователя.

  • Запись будет продолжаться до тех пор, пока в комнате есть хоть один пользователь.

  • Запись останавливается автоматически через ±60  секунд после отключения последнего пользователя. Так, если все участники покинули комнаты, а затем снова присоединились в течение минуты, видеозапись будет продолжена. 

Если один из пользователей забудет закрыть вкладку браузера, он все ещё будет находиться в комнат видеозвонков. Тогда запись будет продолжаться. Не забудьте предупредить пользователей о том, что после окончания видеозвонка вкладку нужно закрыть.  

Найти записанные видео

Записанные видео хранятся в хранилище Стриминговой платформы, так как этот сервис выполняет запись. 

Чтобы найти записи:

1. Откройте ваш личный кабинет Стриминговой платформе по ссылке https://streaming.edgecenter.ru
2. Перейдите в раздел «Видео».
3. Выберите видео с названием «Запись» с подходящим roomID и временем видеозвонка.
4. Откройте видео.
5. Копируйте код видеоплеера, ссылку на плеер, или скачайте запись во вкладке «Экспорт». 

Также вы можете использовать API Стриминговой платформы. Смотрите раздел «Getting Recorded Video”.

Настроить опцию «Запись»

1. Сгенерируйте перманентный API-токен вашего аккаунта, перейдя по ссылке: https://accounts.edgecenter.ru/profile/api-tokens.
2. Используйте параметры:

  • Имя = «Запись видеозвонка» или любое другое.

  • Роль = Администратор

  • Срок действия = Бессрочный.

3. Скопируйте сгенерированный токен.
4. Отправьте скопированный токен нам. 
5. Добавьте дополнительный атрибут &canRecord для модератора или обратитесь к нам, чтобы подключить опцию «Автозапись»

Пример перманентного токена:

1030$0b219f0239c7a418c499a9b0f4d93f0b081700000c346ad254694b15d09981d7cf6b24e41a243df6e9e23d5483820d98921d64c0cb06e9981c842ab31fd0e4db

Синхронный перевод (бета-тест)

При обычном использовании каждый пользователь слышит оригинальный звук видеозвонка. Функция перевода позволяет пользователям слышать речь переводчика в режиме синхронного перевода.

Модераторы, которые хотели бы пригласить переводчиков на свои звонки или вебинары, могут включить синхронный перевод. Организатор может пригласить неограниченное количество (более 20) участников в качестве переводчиков во время видеозвонка.

Когда начинается встреча или вебинар, организатор может включить функцию перевода, которая позволит переводчикам предоставлять свои собственные аудиоканалы для языка, на который они переводят. Затем участники могут выбрать аудиоканал, чтобы услышать переведенный звук на выбранном ими языке. Также есть возможность отключить исходный звук вместо того, чтобы слушать его с меньшей громкостью на выбранном ими языке.

Облачные записи сеансов устного перевода будут записывать только исходный звук встречи или вебинара, но не переводы.

Следующие языки доступны по умолчанию:

  • Китайский, zh

  • Голландский, nl

  • Английский, en

  • Французский, fr

  • Немецкий, de

  • Люксембургский, lb

  • Португальский, pt

  • Русский, ru

  • Испанский, es

  • Шведский, sv

  • Украинский, uk

Если вы хотите использовать другие языки, сообщите нам. 

Для одного языка может быть более одного переводчика. Если по одной ссылке заходят несколько переводчиков, все они смогут говорить в соответствующем канале. Они могут говорить как одновременно, так и/или по отдельности, тогда им нужно просто отключить микрофоны.

Для обычных посетителей новый язык появляется автоматически при подключении переводчика.

Если переводчик отключится от комнаты по собственному желанию или по техническим причинам, то для обычных пользователей выбор языка будет активен и доступен в течение 30 секунд. Если ни один из переводчиков не подключится повторно, то язык исчезнет из списка выбора, а слушатели этого языка переключатся на исходное аудио.

Пример JWT:

PAYLOAD: (DATA) 

{ "role": "interpreter", "featureInterpreters": true, "intLang": “de”, "roomId": "serv0_test1" }
23ddee1bb48243b50f65b2144db2a935.png

API клиента

Интеграция через iFrame

Пример интеграции iFrame

<iframe allow="camera;microphone;fullscreen;display-capture;autoplay;screen-wake-lock" style="height: 100%; width: 100%;" src="https://vconf.edgecenter.ru/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>

Подробнее см. в разделах «Встроить комнату на сайт» и «Параметры атрибутов».

Взаимодействие с iFrame 

Существует специальная библиотека для взаимодействия с iframe, которую нужно подгружать отдельно.

<script type="text/javascript" charset="utf-8" src="https://<yourdomain.edgevideo.ru>/meetBridgeApi.js"></script>

Например:

<script type="text/javascript" charset="utf-8" src="https://vconf.edgecenter.ru/meetBridgeApi.js"></script>

Метод JavaScript-инициализации:

meetIframeBridge = new MeetIframeBridge.default({ element: $iframe.get(0), roomId: "serv1m6oci9e8" });

Где:

  • element – DOM-объект iFrame.

  • roomId — ID комнаты.

Перед инициализацией класса необходимо дождаться загрузки элемента iFrame. 

Публичные методы EdgeConf iFrame

Методы клиентского API позволяют управлять комнатой, выполнять действия со скрытыми основными элементами управления, реагировать на происходящее внутри комнаты.

Пример выполнения метода:

Инициализация

var meetIframeBridge;
$('#meetframe').on("load", function() {
            meetIframeBridge = new MeetIframeBridge.default({ element: $("#meetframe")[0], roomId: "serv1m6oci9e8" });     
});

Присоединение

meetIframeBridge.method({ name: "join", data: {constraints: {video: false, audio: false }}, callback: (e) => { alert(1); return true; } });

Регулировка громкости

meetIframeBridge.method({ name: "setVolume", data: 100, callback: (e) => { alert(1); return true; } });

Изменение имени

meetIframeBridge.method({ name: "changeDisplayName", data: "Tom", callback: (e) => { // return value } });

Получение скриншота видео пользователя

meetIframeBridge.method({ name: "getScreenshotByPeerId", data: "id", callback: (e) => { // “e” parameter will have screenshot data } });

Название метода

Параметры

Описание

join

“constraints”  = object

 

Настройка новых устройств:

data: {constraints: { video: { deviceId: 'id', label: 'label', groupId: 'groupId', kind: 'video'}, audio: { deviceId: 'deviceId', label: 'label', groupId: 'groupId', kind: 'audio'}}}

 

Если вы хотите использовать устройства по умолчанию:

data: {constraints: {video: true, audio: true }}

 

Метод Join получает поток с этих устройств (обычно используется с параметром nameScreenDisabled)

enableMic

 

Включить микрофон

disableMic

 

Отключить микрофон

enableWebcam

 

Включить камеру

disableWebcam

 

Выключить камеру

enableShare

 

Включить демонстрацию экрана

disableShare

 

Выключить демонстрацию экрана

changeDisplayName

“name”

data: string

Изменить имя

setVolume

“volume”

data: number

Установить громкость (0–100)

getScreenshotByPeerId

“peerId”

data: string

Получить скриншот пользователя с id равным peerId, скриншот приведен в Base64

setControlsVisible

“visible”

data: bool

Показать и скрыть элементы управления

isCameraEnabled

 

включена камера пользователя

isMicroEnabled

 

микрофон пользователя включен

isShareEnabled

 

включен общий доступ пользователя

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'}}}

Изменить устройство. Укажите одно устройство для каждого вызова метода

playAudio

 

Запустить звук, который не удалось воспроизвести (обычно используется вместе с autoplayWithoutAudioTrack)

muteAudio

 

Отключить входящий звук

unmuteAudio

 

Включить входящий звук

setBitrate

“bitrateValue”

data: number

Устанавливает максимальный битрейт видео в комнате

isFullscreenEnabled

 

Полноэкранный режим включен

enableFullscreen

 

Включить полноэкранный режим

disableFullscreen

 

Выключить полноэкранный режим

enablePin

“peerId,

data: string

Включить ПИН-код для указанного пользователя

disablePin

 

Отключить ПИН-код для указанного пользователя

setLocale

“locale”

data: string

Динамическая смена языка, доступные языки: en, ru

disabledTrackByModerator

“peerId”, “kind = (audio || video)”

data: {userPeerId: 'peerId', kind: 'audio'}

Отключите видео или аудио от другого пользователя в режиме модератора. Только модератор может отключить видео и аудио

disableAllMics

 

Замьютить микрофоны всех участников. Только модератор может использовать эту опцию.

disableAllCameras

 

Выключить камеры всех участников. Только модератор может использовать эту опцию. 

setHideIndicators

“hide”

data: bool

Указывает на отображение и скрытие индикаторов других пользователей (значки микрофонов, камер, имя пользователя и др.)

События из iFrame 

События на стороне клиента позволяют быстро реагировать на действия/исключения внутри комнаты. 

Пример установки события:

meetIframeBridge.on('switchOnCamera', (e) => { your code here });

Название события

Данные

Описание

join

peerId, displayName

Пользователь добавлен в комнату

ready

iFrame готов к использованию

readyToJoin

К комнате можно подключаться

switchOnCamera

peerId, displayName

Камера включена

switchOffCamera

peerId, displayName

Камера выключена

errorGetCamera

peerId, displayName

Ошибка подключения камеры

switchOnMic

peerId, displayName

Микрофон включен

switchOffMic

peerId, displayName

Микрофон выключен

errorGetMic

peerId, displayName

Ошибка подключения микрофона

switchOnShare

peerId, displayName

Демонстрация экрана включена

switchOffShare

peerId, displayName

Демонстрация экрана выключена

errorGetShare

peerId, displayName

Ошибка демонстрации экрана

newPeer

peerId, displayName

Подключение нового пользователя

peerClosed

peerId, displayName

Пользователь покинул комнату

connectionFailed

 

Соединение с сервером разорвано

disconnected

 

Соединение с сервером закрыто (пример: сервер недоступен)

connectionClosed

 

Пользователь закрыл соединение с сервером

connectionError

peerId, error message

Сообщение об ошибке: ошибка произошла на стороне клиента или сервера

playingAudioPrevent

 

Невозможно воспроизвести звук без щелчка (используется совместно с параметром autoplayWithoutAudioTrack)

switchOnPin

peerId

Функция PIN-кода включена

switchOffPin

 

Функция PIN-кода выключена

errorGetPin

peerId

Ошибка функции вывода

 

API сервера

Конечные точки (endpoints)

Конечные точки (endpoints) видеозвонка

См. спецификацию REST API. Ниже приведен краткий список конечных точек.

Чтобы получить доступ к методам API сервера, вам необходимо пройти аутентификацию. См. раздел «Аутентификация» ниже.

Название метода

Параметры

Описание

/rooms/:roomId/closePeer

peerId, 

body:{peerId: id}

Удалить пользователя из комнаты, POST

/rooms/:roomId/durationOfBroadcast

 

Установить, как долго существует комната, GET

/rooms/:roomId/closeRoom

 

Удалить комнату, GET

/rooms/:roomId/numberPeers

 

Установить число участников, GET

/rooms/:roomId/existingPeer

peerId,

body:{peerId: id}

Установить, есть ли пользователь в комнате или нет

Пример запроса: 

https://webrtc1.edgelive.ru:443/<roomId>/closeRoom

Общие коды ответов

Код

Метка ответа

Описание

200

OK

ОК

400

Bad Request

Токен, ID комнаты или peerId не найдены

401

Unauthorized

Доступ отказан, свяжитесь с администратором

403

Forbidden

Некорректный токен

404

Not found

Некорректный ID комнаты

500

Internal Server Error

Ошибка соединения с сервером

Доступные серверы

EdgeЦентр предоставляет клиентам сервер для общего использования. Имя сервера наследуется от идентификатора комнаты.

Например: &roomId = serv1qweqwe

Сервер

Страна

URL сервера

Описание

serv0

Россия, Москва (сервер №1)

https://webrtc1.edgelive.ru:443

Сервер по умолчанию,
если явно не указан другого. Например: &roomID=LADA

serv1

Россия, Москва (сервер №2)

https://webrtc2.edgelive.ru:443

В URL-адресе сервера есть смещение. Это временное, но необходимое решение. Скоро мы изменим адрес. Об изменениях сообщим дополнительно.  

В целях отладки вы можете напрямую вызывать конечную точку сервера. Но для публичного использования мы применяем строгие ограничения и повышаем уровень безопасности. Пожалуйста, напишите нам, с каких серверов и с какими параметрами безопасности будут разрешены серверные вызовы, все остальные вызовы будут отклонены.

Пример проверки работоспособности видеосервера

Метод вызова, например

https://webrtc1.edgelive.ru/rooms/ser0l8bsg8zw1/durationOfBroadcast

Для несуществующей комнаты ответ 400.Если ошибка 500 или исчерпан таймаут, сервер недоступен.

Вебхуки

Вехуки — это определяемые пользователем обратные вызовы, запускаемые событиями собрания. Вебхуки отправляются на URL-адрес, указанный в атрибуте apiEvent:

Название события

Параметры

Описание

joinPeer

roomId, peerId, displayName

Новый пользователь подключен

closePeer

roomId, peerId, displayName

Пользователь был отключен

 

Вебхук joinPeer

Метод уведомления о том, что участник присоединился к комнате. Этот метод используется для дополнительной проверки авторизации на вашей стороне.

POST /joinPeer

Атрибуты:

  • roomId

  • peerId

  • displayName

Пример:

{"event":"connected","roomId":"44fde071","peerId":"de9b6927",“displayName”:”user16”
https://vconf.edgecenter.ru/call/?roomId=44fde071&displayName=user16&accessToken=caa630bb&peerId=de9b6927&apiEvent=https://dev.com/api/events&accessUrl=https://dev.com/api/accesscheck

Вебхук closePeer

Метод уведомления о закрытии соединения между сервером и браузером участника. В большинстве случаев это означает, что участник сам вышел из комнаты или возникла проблема с интернет-соединением.

POST /closePeer

Атрибуты:

  • roomId

  • peerId

  • displayName

Пример: 

{"event":"disconnected","roomId":"44fde071","peerId":"de9b6927",“displayName”:”user16”}

Специальный API «Стриминговой платформы»

Инструмент для видеоконференций управляет данными в режиме реального времени. Таким образом, API сервера и API клиента предназначены для управления поведением пользователей и видеокомнат в режиме реального времени.

Статистика использования и записи видео хранятся в «Стриминговой платформы». Таким образом, пожалуйста, используйте REST API видеоплатформы для этих методов.

Чтобы получить доступ к API платформы видео, вам необходимо пройти аутентификацию. См. раздел «Аутентификация участников и ограничение доступа» выше.

Статистика использования

Инструмент для видеозвонков отправляет данные об использовании каждые 30 секунд на серверы «Стриминга». Это означает, что статистика использования всегда кратна 30 секундам.

1) Общая информация об использовании комнаты:

Это сводные данные по комнате.

GET /streaming/statistics/peers/summary

Атрибуты:

  • room_id

  • from – начальная точка отсчета

  • to – конечная точка отсчета

Коды ответов:

200 – OK, json-объект с данными.
400 – Bad Request, в случае некорректных значений атрибутов.
403 – Unauthorized access (неавторизованный доступ).
404 – Not found, в случае никаких данных по комнате или комнате в статистике не обнаружено.
500 – Internal error (внутренняя ошибка).

Значения:

  • participants – общая сумма уникальных участников в комнате.

  • start_time – unix-время в секундах времени первого входа первого участника, например = 1624276920.

  • end_time – unix-время в секундах самого последнего участника, уходящего, например = 1624358940.

  • duration – секунды активности комнаты, рассчитываемые как разница между значением параметра end_time и значением параметра start_time. например = 90660.

Обратите внимание: результат содержит агрегированные данные по всем сеансам указанной комнаты в период «с» по период «до». Если вы используете один и тот же идентификатор комнаты каждый день, то отдельные периоды.

Например, https://vconf.edgecenter.ru/call/?roomId=serv0test1 используется в течение 60 мин. каждый день в понедельник, 21 июня, и во вторник, 22 июня.

  • /summary?from=2021-06-21T00:00:00.0Z&to=2021-06-21T23:59:59.99Z&room_id=serv1test1 – вернет 60 мин. (60 мин. 21 июня).

  • /summary?from=2021-06-21T00:00:00.0Z&to=2021-06-22T23:59:59.99Z&room_id=serv1test1 – вернет 120 мин. (60 мин. 21 июня + 60 мин. 22 июня).

Пример использования:

https://api.edgecenter.ru/streaming/statistics/peers/?from=2021-06-21T00:00:00.0Z&to=2021-06-22T23:59:59.99Z&room_id=serv1test2a

Пример возвращенных данных:

{
    "data": {
        "participants": 3,
        "start_time": 1624268280,
        "end_time": 1624358940,
        "duration": 90660
    },
    "errors": []
}

2) Подробная информация для каждого участника:

Это данные по сеансам каждого участника для комнаты.

Если событие длилось 60 мин., и пользователь заходил первые 5 мин. затем выходил из комнаты, и снова присоединялся последние 5 мин., то в статистике будет отражено 2 сеанса по 5 мин. + 5 мин. = 10 мин. (т.е. 600 с. вместо 3 600 с. от общей продолжительности)

GET /streaming/statistics/peers/

Атрибуты:

  • room_id

  • from – начальная точка отсчета

  • to – конечная точка отсчета

Коды ответов:

200 – OK, json-объект с данными.
400 – Bad Request, в случае некорректных значений атрибутов.
403 – Unauthorized access (неавторизованный доступ).
404 – Not found, в случае никаких данных по комнате или комнате в статистике не обнаружено.
500 – Internal error (внутренняя ошибка).

Значения:

  • массив сеансов участников.

  • person_id – данные peerId (ваше значение, если оно было указано в атрибутах URL, или уникальный GUID, созданный автоматически, если он был опущен).

  • join_time – время unix в секундах времени входа участника, например, 1624268280.

  • leave_time – unix-время в секундах времени выхода участников, например, 1624269300.

  • duration – количество секунд сеанса, например, 1 260.

 Пример использования:

https://api.edgecenter.ru/streaming/statistics/peers/summary?from=2021-06-21T00:00:00.0Z&to=2021-06-22T23:59:59.99Z&room_id=serv1test2a

Пример возвращаемых данных:

{
    "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": []
}

Получение записанного видео

Записи комнаты хранятся в медиахранилище Стриминговой платформы. Вам нужно найти видео, а затем получить его по ID.

1) Найти видео

GET /streaming/videos/search

Атрибуты:

  • q – поисковый запрос. Поиск осуществлялся среди всех названий видео. В качестве поискового запроса укажите roomId.

Значения:
  • Массив доступных видео для указанного идентификатора.

Если сеанс длился более 4 часов, то записанный сеанс будет разделен на несколько видео продолжительностью по 4 часа каждое. В этом случае вам нужно получить все видео отдельно.

2) Получить метаданные видео

GET https://api.edgecenter.ru/streaming/videos/{video_id}

Выходные значения:

  • Метаданные видео. Используйте поля «hls_url» для использования потока .m3u8 во внешних проигрывателях или «origin_host»+«origin_resource» для получения исходного файла MP4.

Пример возвращаемых данных: 

{ 
  "hls_url": "https://id10835.edgecenter.ru/videos/10835_UaX2pjxen2guUw3/master.m3u8", 
  "origin_host": "s-ed1.cloud.edgecore.ru", 
  "origin_resource": "9208-mediaplatform10835/videos/UaX2pjxen2guUw3.mp4", 
}

Ограничение скорости

Существует общий лимит в 4 запроса в секунду. Если вы превысите лимит скорости, вы получите уведомление.

Безопасность

Защитить видеозвонки

Запретить конечным пользователям изменять настройки комнаты

Чтобы защититься от изменений конфигураций конечными пользователями, поместите атрибуты в токен JWT с цифровой подписью.

Например, атрибут &role=moderator следует добавить не в строку URL, а внутрь &token= с цифровой подписью.

Использовать дополнительные атрибуты URL с JWT

Чтобы расширенные параметры не были скомпрометированы, вам необходимо подтвердить, что вы их устанавливаете.

JWT — это набор параметров с вашей цифровой подписью. Таким образом, вы подтверждаете, что именно вы создали этот набор данных.

1. Приготовьте публичный и приватный ключ (подробнее об этом в блоке «Генерация открытых и секретных ключей RSA»).

2. Сохраните приватный ключ.

3. Отправьте публичную часть ключа нам через персонального менеджера или техподдержку.

4. Выберите атрибуты, которые вам нужны из таблицы «URL-атрибутов для расширенной настройки». 

5. Добавьте нужные атрибуты в JWT, затем подпишите JWT с помощью публичного ключа. Подробнее в блоке «Проверка запросов с помощью JWT». 

6. Присоедините JWT с помощью атрибута &token= в URL (подробнее в блоке статьи &token=<jwt>).

Контролировать срок действия доступа в комнаты

По умолчанию функция проверки запросов с помощью JWT отключена. В этом случае любой пользователь может сгенерировать параметр &roomId=XXX и открыть указанную комнату.

Используйте JWT, если хотите убедиться, что:

- RoomId создается только вами.

- Роли пользователей задаете только вы.

- Функция переводчиков устанавливается только вами.

Получить полный контроль над каждым подключением пользователей в систему

Подробнее в блоке «Как контролировать срок действия доступа в комнаты». Этого решения достаточно для большинства случаев.

Если нужно контролировать все действия пользователей, доступна интеграция с вашей внутренней системой аутентификации

  • Подключиться к вашей корпоративной системе аутентификации. 

  • Разрешить или отказать подключение пользователя.

  • Предотвратить подключение незарегистрированных пользователей.

  • Сделать комнату закрытой до запланированного времени и после окончания мероприятия.

  • Ограничить максимальное количество участников и так далее.

Подробнее в блоке статьи «Расширенная аутентификация участников и ограничение доступа».

Проверка запросов с помощью JWT

Что такое JWT

Для доступа к API клиента мы используем JWT — веб-токены JSON — это открытый метод промышленного стандарта RFC 7519 для безопасного представления требований между двумя сторонами.

Подробнее об использовании JWT на странице https://jwt.io/introduction

JWT позволяет точно определить валидность настроек комнаты и однозначно определить принадлежность токена к вашему аккаунту.

Чтобы использовать JWT, вам нужен открытый и секретный ключ. Новый ключ генерируется вами. Отправьте публичную часть вашего ключа через техподдержку или персонального менеджера. Подробнее см. в разделе «Генерация открытых и секретных ключей RSA» ниже.

Ограничения использования JWT

Вы можете активировать опцию использования JWT в своей учетной записи. Если вы активируете эту опцию, то необходимо будет отправлять JWT &token=xxx в каждом запросе. Без указания токена на экран будет выведено сообщение «Отказано в доступе».

Если вы активируете использование токена JWT, вы не сможете использовать атрибут &accessToken=xxx.

JWT-заголовок

Заголовок обычно состоит из двух частей: тип токена и используемый алгоритм подписи.

  • RS256 — асимметричный ключ,

  • HS256 — симметричный ключ.

HEADER:ALGORITHM & TOKEN TYPE 
{
"typ": "JWT",
"alg": "RS256"
}
HEADER:ALGORITHM & TOKEN TYPE 
{ 
  "typ": "JWT", 
  "alg": "HS256" 
}

JWT-body

Body (тело) JWT содержит важные данные, которые необходимо подписать и проверить. Данные внутри JWT имеют более высокий приоритет, чем значения тех же параметров, указанных в атрибутах URL. Это означает, что если значение атрибута одновременно указано и внутри JWT, и в наборе атрибутов URL, то будет использовано значение из JWT.

См. список параметров, которые можно установить внутри JWT, в таблице атрибутов выше.

Приоритет использования внутри JWT и из URL:

  • Параметры с меткой «JWT» могут быть указаны внутри токена или в качестве атрибута в URL-адресе. Если значение атрибута указано в токене, то значение в URL-адресе игнорируется. Если атрибут не указан в токене, то значение атрибута будет взято из URL.

  • Параметры с меткой «URL» можно указывать только как атрибут в URL.

Дополнительный список атрибутов для использования JWT:
  • startTime – планируемое время начала мероприятия в комнате. См. «Метод Вебхук joinPeer».

  • iat  (опционально) — указывает время выпуска JWT. Этот атрибут можно использовать, чтобы определить «возраст» JWT. Его значение должно быть числом (NumericDate). 

Список атрибутов расширяется, расскажите какие атрибуты (из общего списка атрибутов URL) вам нужны внутри токена.

PAYLOAD:DATA
{
"roomId": "abcd1234",
"role": "moderator",
"startTime": "2022-06-21T00:00:00.0Z "
}
Пример:
https://vconf.edgecenter.ru/call/?roomId=YOUR_ROOM_ID&token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoibW9kZXJhdG9yIiwic3RhcnRUaW1lIjoiMjAyMS0wNi0yMVQwMDowMDowMC4wWiJ9.Atj-TPL_GSLyuI565pI6X_6GFjopXf62C6y4OgeeEk9KEb_1cosDmo2sytpBv44PRuMRwgDg8AcqlMMgA0kcdJrBZ7AAywjb6RZVXlian6-6XQ0zx7OhYyDo2-mVxCO9dgYroXfz2Fw8lyNuqFl0AKEfFMPKaYf46u5kjwWmSyhh7bLbL969Eu3zW_Mk3sYLpW_xULyndhkXrLqOVspK08Mla-AbxGJ94pZXJCKHK5UslhrGJ6RProN5nL4NaXOCKRX0ffKnklxiyn9MgKf0cc6Za0GCpjg-d3y6-UOVd0AXW8TWR-RllTgXaTUMMSLyWzHPsv-e2O-GsA0WJnBJEg

Подпись JWT

Используйте свой ключ для подписи токена по алгоритму, указанному в заголовке.

Подпись используется для проверки того, что данные не были изменены. В случае токенов, подписанных с помощью закрытого ключа, она также может проверить, что отправитель JWT является тем, кем он себя называет.

Мы рекомендуем использовать алгоритм асимметричного типа RS256. См. «Генерация открытых и секретных ключей RSA», чтобы узнать, как сгенерировать открытые/закрытые ключи.

Проверка запросов API сервера

Проверка с использованием заголовка авторизации

Для доступа к API сервера и API потоковой платформы мы используем токен API в заголовке авторизации. Токен API — это уникальный ключ, который все пользователи и приложения должны добавлять в запросы для взаимодействия с нашими сервисами.

Пройдите аутентификацию через API EdgeЦентра. Выберите один из методов: Bearer-аутентификация или аутентификация по перманентному токену. 

Bearer-аутентификация

Токен будет предоставлен по запросу на вход с логином и паролем от личного кабинета. В ответ вы получите два токена: доступа (access) и обновления (refresh).

Для управления службами API сервера добавьте свой токен доступа после Bearer в заголовке авторизации следующим образом:

Authorization: Bearer eyJ0eXAiOiJKV

Используйте запрос на обновление, чтобы обновить токен доступа.

1. Авторизуйтесь (например, через Postman), используя свое имя пользователя и пароль.
2. Вы получите два значения токенов «доступ» и «обновление».
3. Токен «доступ» содержит токен, который активен в течение нескольких часов (24 часа, но мы рекомендуем обновлять его каждые 4 часа).
4. Кроме того, в каждую конечную точку необходимо передать заголовки аутентификации: «Авторизация»: Bearer ${token} '.
5. Если токен правильный, все в порядке.
6. Если нет, будет возвращена ошибка 401.

Расширенная аутентификация участников и ограничение доступа

Мы позволяем интеграцию с вашими системами контроля пользователей. Это может быть внешняя CMS, LMS или любой сервер безопасности. Вы можете проверить каждого пользователя, который входит в комнаты.

Наш сервер делает вызов указанного метода в атрибуте &accessUrl. Ваш сервер должен вернуть код, как показано ниже. В зависимости от этого кода принимается решение открывать комнату или нет.

Если доступ к указанному методу защищен через Basic-авторизацию, то необходимо прописать необходимый заголовок в атрибуте &authorizationAccess=<header>.

Эти атрибуты отладки можно использовать в URL-адресе. Но для публичного вам нужно сообщить нам, чтобы зарегистрировать методы на сервере.

Пример:

https://vconf.edgecenter.ru/call/?roomId=44fde071&displayName=user16&accessToken=caa630bb&peerId=de9b6927&apiEvent=https://dev.com/api/events&accessUrl=https://dev.com/api/accesscheck

Входные значения:

  • accessToken – уникальный идентификатор безопасности из атрибута &accessToken

  • roomId – идентификатор комнаты из атрибута &roomId

  • peerId – идентификатор участника из атрибута &peerId

Пример:

{"accessToken":"caa630bb","roomId":"44fde071","peerId":"de9b6927"}

Выходные коды, которые мы ожидаем с вашей стороны:

Код

Метка ответа

Описание

200

OK

Участник может присоединиться к комнате.

400

Bad Request

Токен, roomId, peerId не найдены.

401

Unauthorized

Участник не может присоединиться
к комнате, доступ отклонен.

403

Forbidden

Некорректный токен

404

Not found

Некорректный ID комнаты

409

Conflict

Соединение было обнаружено
с существующим идентификатором узла. 

В этом случае устанавливается
новое соединение, а старое разрывается.

Пользователю показывается сообщение
в браузере «Кто-то присоединился
к комнате с вашим id».

423

Locked

Доступ закрыт временно или навсегда
для неактивных комнат. 

Когда вы сами закрываете или
ограничиваете максимальное
количество участников. 

Он предназначен для отображения
удобочитаемого сообщения
о причинах и контактах для модератора, 

вместо простого сообщения «отказано в доступе».

425

Too Early

Доступ временно закрыт для тех событий,
которые еще не начались. 

Выводим удобочитаемое сообщение
«Событие еще не началось. Старт %d%». 

Время начала берется из JWT.

500

Internal Server Error

Ошибка соединения с сервером.

Другие примеры:

  • Чтобы запретить незарегистрированным пользователям присоединяться – отправить 401 Locked для запросов с пустым peerId. 

  • Чтобы закрыть комнату после окончания мероприятия – отправить 423 Закрыто для всех запросов после окончания мероприятия. 

  • Чтобы ограничить максимальное количество участников – отправить 423 Заблокировано для всех запросов после достижения максимума, возобновить 200 OK при уменьшении количества участников, когда кто-то уходит.

Решение проблем

Алгоритм цифровой подписи JWT

Мы используем алгоритм RS256 или HS256 для подписи и генерации хэша.RS256 относится к хеш-функции SHA256. RFC указана в https://tools.ietf.org/html/rfc7518#page-8

"alg" Значение параметра

Алгоритм цифровой подписи

RS256

RSASSA-PKCS1-v1_5 используемый в SHA-256

HS256

HMAC используемый в SHA-256

Используйте https://jwt.io/, чтобы верифицировать JWT-токен.

  • Ключ RSA размером 2048 бит или больше следует использовать с этим алгоритмом.

  • Ключ HS должен быть того же размера, что и хеш (256 бит для HS256 и больше).

Цифровая подпись RSASSA-PKCS1-v1_5 SHA-256 создается следующим образом: сгенерируйте цифровую подпись ввода подписи JWS, используя RSASSA-PKCS1-v1_5-SIGN и хэш-функцию SHA-256 с желаемым закрытым ключом. Это значение подписи JWS.

Подробности см. в разделе «Генерация открытых и секретных ключей RSA» ниже.

Генерация открытых и секретных ключей RSA

Ключи могут быть сгенерированы любым инструментом генерации ключей RSA.

Мы рекомендуем использовать инструмент OpenSSL

Чтобы выполнить следующие действия для Windows или Linux, проверьте и/или установите OpenSSL в своей системе.

Команды для генерации секретного ключа и экспорта открытого ключа:

  1. openssl genrsa -out key_name.key 2048

  2. openssl rsa -in key_name.key -pubout -outform PEM -out key_name.key.pub

Файл имя_ключа.key.pub будет содержать открытую часть ключа. Файл key_name.key будет содержать приватную часть ключа.

Число 2048 в приведенной выше команде указывает размер закрытого ключа.

Вы можете выбрать 2048 или 4096 (эти числа представляют биты).

Большие размеры обеспечивают большую безопасность, но это компенсируется снижением производительности процессора.

Мы рекомендуем выбирать 2048.

Помогла ли вам статья?