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

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

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

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

  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

Вставьте комнату для видеозвонков на свой сайт или в приложение через 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

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

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

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

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

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

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

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

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

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

1. iOS Native SDK
2. WebView

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

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

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

2. 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 типах доменов:

  • companyname.edgevideo.ru — пример специального домена в нашей зоне edgevideo.ru.

  • video.domain.com — пример внешнего домена.

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

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

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

&accessUrl=<url>

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

JWT, URL

&apiEvent=<url>

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

JWT, URL

&authEvent=<header>

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

JWT, URL

&authorizationAccess=<header>

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

JWT, 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

&maxWatchers=<num>

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

JWT

&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

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

&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​>

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

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

  • Русский = ru

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

  • Немецкий = de

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

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

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

Например:

&lаng=ru

&maxBroadcasters=<​num​>

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

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

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

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

Например:

&maxBroadcasters=10

&maxWatchers=<​num​>

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

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

Например:

&maxWatchers=50

&minimizeTiles=<​true|false​>

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

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

Например:

&minimizeTiles=true

&muteSoundNotification=<​true|false​>

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

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

Например:

&muteSoundNotification=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 комнаты. ID сервера — servN, см. Список серверов. ID комнаты — это любой буквенно-цифровой набор символов. Если сервер не указан, то вас подключат к серверу по умолчанию. Если указан — к конкретному.

&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​>

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

JWT позволяет:

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

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

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

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

Например: 

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

&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 для авторизации на стороне клиента.. Подробнее см. в разделе Безопасность. Не забудьте использовать 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​>

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

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

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

Например:

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

&authorizationAccess=<​header​>

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

Пожалуйста, не используйте этот атрибут публично. Для публичного использования 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. Откройте ваш личный кабинет Стриминговой платформы.
2. Перейдите в раздел Видео хостинг.
3. Выберите видео с названием «Запись» с подходящим roomID и временем видеозвонка.
4. Откройте видео.
5. Скопируйте код видеоплеера, ссылку на плеер, или скачайте запись во вкладке Экспорт. 

Вы также можете использовать API Стриминговой платформы. Смотрите раздел Получить записанное видео.

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

1. Сгенерируйте перманентный API-токен вашего аккаунта.
2. Используйте параметры:

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

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

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

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

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

1030$0b219f0239c7a418c499a9b0f4d93f0b081700000c346ad254694b15d09981d7cf6b24e41a243df6e9e23d5483820d98921d64c0cb06e9981c842ab31fd0e4db

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

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

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

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

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

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

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

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

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

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

  • Немецкий, de

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

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

  • Русский, ru

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

  • Шведский, sv

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

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

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

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

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

Пример JWT:

PAYLOAD: (DATA) 

{ "role": "interpreter", "featureInterpreters": true, "intLang": “de”, "roomId": "serv0_test1" }

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&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

data: { audio: { deviceId: 'deviceId', label: 'label', groupId: 'groupId', kind: 'audio'}}

 

или

 

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

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

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: {peerId: '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

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

switchOnPin

peerId

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

switchOffPin

  

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

errorGetPin

peerId

Ошибка функции PIN

API сервера

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

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

Обратитесь к спецификации REST API. Ниже приведён краткий список конечных точек.

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

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

Параметры

Описание

/rooms/:roomId/closePeer

peerId, 

body:{peerId: id}

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

/rooms/:roomId/durationOfBroadcast

  

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

/rooms/:roomId

  

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

/rooms/:roomId/numberPeers

  

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

/rooms/:roomId/existingPeer

peerId,

body:{peerId: id}

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

/chat/clear-rooms

body: { hostname: string, rooms: [{roomId: id, type: “call”/”webinar”}]}

Очистить истории чата в определённых 

комнатах, POST

где: 

  • hostname — доменное имя

  • type — тип комнаты (необязательно), а call — значение по умолчанию

/rooms/:roomId/recording/start

Запустить запись для определённой комнаты, POST

/rooms/:roomId/recording/stop

Остановить запись, POST

/rooms/:roomId/recording

Проверить статус записи, GET

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

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

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

Код

Метка ответа

Описание

200

OK

ОК

400

Bad Request

hostname, client_id, rooms недействительны

401

Unauthorized

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

403

Forbidden

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

404

Not found

Некорректная конечная точка (endpoint)

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&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

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

Например, 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 с. вместо 3600 с. от общей продолжительности)

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 — количество секунд сеанса, например, 1260.

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

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
        }
    ],
    "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-dt2.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-заголовок

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

  • 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. Дата и время указываются в часовом поясе UTC в миллисекундах в формате ISO 8601.

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

Мы расширяем список атрибутов, поэтому расскажите какие атрибуты (из общего списка атрибутов 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-аутентификация или аутентификация по перманентному токену. 

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

'Authorization: APIKey eyJ0eXAiOiJKV'

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

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

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

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

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

Пример:

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

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

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

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

Пример:

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

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

Код

Метка ответа

Описание

200

OK

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

400

Bad Request

Token, 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 Unauthorized для запросов с пустым peerId. 

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

  • Чтобы ограничить максимальное количество участников, отправьте 423 Locked для всех запросов после достижения максимума. Отправьте 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.

Мы рекомендуем использовать инструмент 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_name.key.pub будет содержать открытую часть ключа. Файл key_name.key будет содержать приватную часть ключа.

Число 2048 в приведенной выше команде указывает размер приватного ключа. Вы можете выбрать 2048 или 4096 (эти числа представляют биты). Большие размеры обеспечивают большую безопасность, но это компенсируется снижением производительности процессора. Мы рекомендуем выбирать 2048.

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