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

API клиента (интеграция через iframe)

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

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

Например:

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

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

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

Где:

• element — DOM-объект iframe

• roomId — ID комнаты

Публичные методы 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 } });

События из iframe

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

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

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

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

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

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

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

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

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

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

Вебхуки

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

Вебхук joinPeer

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

POST /joinPeer

Атрибуты:

• roomId

• peerId

• displayName

Пример:

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

https://edgeconf.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://edgeconf.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 https://api.edgecenter.ru/streaming/vod/videos/search 

Атрибуты:

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

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

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

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

GET https://api.edgecenter.ru/streaming/vod/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.

• 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://edgeconf.ru/call/?roomId=YOUR_ROOM_ID&token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoibW9kZXJhdG9yIiwic3RhcnRUaW1lIjoiMjAyMS0wNi0yMVQwMDowMDowMC4wWiJ9.Atj-TPL_GSLyuI565pI6X_6GFjopXf62C6y4OgeeEk9KEb_1cosDmo2sytpBv44PRuMRwgDg8AcqlMMgA0kcdJrBZ7AAywjb6RZVXlian6-6XQ0zx7OhYyDo2-mVxCO9dgYroXfz2Fw8lyNuqFl0AKEfFMPKaYf46u5kjwWmSyhh7bLbL969Eu3zW_Mk3sYLpW_xULyndhkXrLqOVspK08Mla-AbxGJ94pZXJCKHK5UslhrGJ6RProN5nL4NaXOCKRX0ffKnklxiyn9MgKf0cc6Za0GCpjg-d3y6-UOVd0AXW8TWR-RllTgXaTUMMSLyWzHPsv-e2O-GsA0WJnBJEg

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

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

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

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

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

'Authorization: APIKey eyJ0eXAiOiJKV'

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

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

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

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

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

Пример:

https://edgeconf.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"}

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

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

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

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

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

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

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

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

Используйте 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.