Керуйте відео та прямими трансляціями зі свого сайту через DCAST API

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

Підключіть свій сайт до 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 у зібраних сторінках і в журналі мережі браузера; він не повинен з'являтися ніде. По-друге, завантажте малий файл, великий файл і непідтримуваний файл та переконайтеся, що кожне завантаження завершується станом, який ваш інтерфейс може пояснити. По-третє, відкрийте галерею як відвідувач без входу й перевірте, що незавершені відео приховано. По-четверте, запитайте плеєр для неіснуючого ідентифікатора й переконайтеся, що ваша сторінка коректно деградує, а не показує порожній кадр.

Коли ці перевірки пройдено, ваші відвідувачі бачать один сайт, ваш код керує робочим процесом, а відеоплатформа залишається у тіні. Почніть з одного завантаження та однієї сторінки галереї, а трансляції додайте, коли перша частина працюватиме без збоїв.