Видео и прямые эфиры на вашем сайте через API DCAST

Если у вашего продукта уже есть собственные страницы, пользователи и база данных, отправлять людей в отдельную панель управления видео — шаг назад. Вам нужно, чтобы ваш код сам добавлял видео, получал их список и запускал трансляции, а посетители оставались на вашем сайте. В этой статье разбирается такая настройка с помощью API DCAST: какие решения принять в начале и какие сбои проверить до запуска.

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

Храните ключ на сервере и решите, кому что принадлежит

Прежде чем писать код загрузки, решите, где будет храниться ключ API. Держите ключ API на своём сервере и никогда не помещайте его на страницу, которую загружают посетители. Любой, кто откроет исходный код страницы или журнал сетевых запросов, сможет скопировать ключ, отправленный в браузер, и с этого момента сможет действовать от имени вашего аккаунта. Храните его в переменной окружения, не добавляйте в систему контроля версий и позвольте браузеру обращаться только к маршрутам вашего собственного бэкенда. Эти маршруты должны проверять, что посетителю разрешена загрузка, прежде чем обращаться к API видео.

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

Загрузка видео из вашего кода

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

Каждый запрос на загрузку возвращает адрес, на который ваш сайт отправляет видеофайл, и адрес статуса, который сообщает сайту, когда видео готово к показу.

Сам файл отправляется на возвращённый адрес загрузки запросом PUT.

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

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

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

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

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

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

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

Каждое видео в списке показывает свой статус, например ready, вместе с адресом страницы его плеера.

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

Постройте галерею из вашей библиотеки

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

Список ваших видео содержит только видео аккаунта, которому принадлежит ключ, и никогда не содержит видео другого аккаунта.

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

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

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

Разместите плеер на странице

Код плеера предоставляется в виде простого адреса, в виде фрагмента iframe и в виде адаптивной версии, которая масштабируется вместе со страницей.

Код плеера — это iframe, который вы размещаете на своей странице.

Выбирайте по макету. Используйте адаптивную версию на страницах статей и в сетках карточек, где ширина меняется в зависимости от экрана. Используйте простой адрес, когда хотите собрать iframe самостоятельно, например чтобы добавить атрибут title, который помогает программам чтения с экрана. Проверьте страницу на настоящем телефоне до запуска, потому что рамка фиксированного размера — самая частая причина того, что встроенное видео выглядит сломанным на мобильных устройствах.

Вы можете разместить плеер ваших видео и трансляций на своём сайте с помощью короткого кода встраивания.

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

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

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

Запускайте прямые эфиры из своего кода

Ваш сайт создаёт прямой эфир через API и получает адреса для публикации вместе с кодом плеера для страницы, на которой показывается трансляция.

Новая трансляция поставляется с адресом RTMP, адресом SRT и, где это доступно, адресом HTTPS для WHIP.

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

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

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

Выполните эти проверки до запуска

Пройдите этот короткий список по порядку. Во-первых, поищите ключ API в собранных страницах и в журнале сетевых запросов браузера; он не должен встречаться нигде. Во-вторых, загрузите маленький файл, большой файл и неподдерживаемый файл и убедитесь, что каждая загрузка заканчивается состоянием, которое ваш интерфейс может объяснить. В-третьих, откройте галерею как незалогиненный посетитель и проверьте, что неготовые видео скрыты. В-четвёртых, запросите плеер для несуществующего идентификатора и убедитесь, что ваша страница корректно обрабатывает это, а не показывает пустую рамку.

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