Модуль Kinescope для Drupal

Если ваш сайт работает на Drupal, видео из Kinescope можно добавлять в материалы через модуль Kinescope. Вы вставляете ссылку на видео в поле, а модуль выводит на странице плеер Kinescope. Модуль поддерживает Drupal 10 и 11, текущая версия — 1.3.1.

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

Когда вам пригодится модуль

• Видео в материалах — плеер в статье, на странице или в блоке через отдельное поле.
• Видео в медиатеке Drupal — ролики Kinescope хранятся рядом с картинками и документами, их можно подставлять в любые материалы.
• Данные видео без ручного ввода — с API-токеном модуль сам подтягивает название, описание, длительность и постер.
• Управление плеером из JavaScript — модуль подключает IFrame API, а события плеера вы обрабатываете в коде темы.
• Видео во всплывающем окне — на странице постер со ссылкой, плеер открывается поверх страницы.

Если хотя бы один из этих сценариев вам знаком — читайте дальше.

Из чего состоит модуль

Проект разделён на четыре модуля. Включайте только те, что вам нужны.

Как работает модуль (4 шага)

1. Вы загружаете видео в Kinescope и копируете ссылку на него.
2. Вставляете ссылку в поле Kinescope или добавляете видео в медиатеку Drupal.
3. Если задан API-токен, модуль запрашивает в Kinescope данные видео.
4. Drupal выводит плеер Kinescope выбранным способом встраивания.

Теперь разберём, как это настроить.

Установка

1. Установите модуль через Composer:

   composer require drupal/kinescope
   

2. В админке Drupal откройте Extend (/admin/modules).

3. Отметьте Kinescope и Kinescope Player. Если нужно, отметьте также Kinescope Media и Kinescope Popup.

4. Нажмите Install.

Настройка модуля

Все настройки собраны на странице Configuration → Media → Kinescope settings (/admin/config/media/kinescope). Открыть её может роль с правом Administer Kinescope settings.

Режим без токена и с токеном

Модуль работает и без API-токена — это режим по умолчанию. Токен добавляет данные о видео из Kinescope API.

С токеном модуль запрашивает данные видео методом GET /v1/videos/{video_id}.

Чтобы подключить токен:

1. В Kinescope откройте Настройки → API-токены и создайте токен. Подробнее о токенах — в статье «Общие правила API».
2. В Drupal на странице настроек Kinescope вставьте токен в поле API token.
3. Нажмите Save configuration.

Токен можно задать и в файле settings.php:

// Токен Kinescope API для модуля Kinescope
$settings['kinescope.api_token'] = 'ВАШ_API_ТОКЕН';

Значение из settings.php главнее: поле API token в форме становится недоступным, а под ним появляется пометка, что токен задан в файле.

Проверить, видит ли Drupal токен, можно в Reports → Status report (/admin/reports/status). В строке Kinescope API token будет Configured или предупреждение Not configured.

Способ встраивания плеера

На той же странице, в блоке Player, выберите Embed method. Настройка общая: она действует для всех полей Kinescope на сайте.

IFrame API. Модуль только подключает плеер к IFrame API. Код, который управляет плеером и обрабатывает его события, вы добавляете в тему сами — примеры есть в статье «Автоподключение к IFrame API».

Web Components. В этом режиме модуль передаёт элементу только ссылку на видео. Ширина, высота и значение Allow-list options из настроек поля не применяются.

Видео в поле материала

Этот способ не требует медиатеки: видео хранится прямо в поле материала. Поле Kinescope можно добавить в любой тип сущности — материал, блок, абзац.

1. Откройте Structure → Content types и выберите тип материала.
2. Нажмите Manage fields и добавьте новое поле с типом Kinescope.
3. В настройках поля решите, кто задаёт параметры плеера. За это отвечает флажок Allow editors to override player settings per video:
   • включён (по умолчанию) — редактор задаёт параметры для каждого видео в форме материала;
   • выключен — вы задаёте параметры один раз в настройках поля, и они действуют для всех видео в нём.
4. Сохраните настройки поля.

Параметры плеера:

Теперь добавьте видео в материал:

1. В Kinescope скопируйте ссылку на видео: кнопка «Ссылка» над плеером → «Копировать».
2. В форме материала вставьте её в поле Kinescope URL.
3. Сохраните материал. Поле Kinescope ID заполнится автоматически.

Поле принимает ссылки такого вида:

• https://kinescope.io/ID_видео
• https://kinescope.io/embed/ID_видео

Ссылка должна начинаться с https:// и не содержать параметров после ?. Иначе Drupal покажет ошибку The Kinescope URL is not valid.

Видео в медиатеке Drupal

Для этого способа включите Kinescope Media. Модуль не создаёт тип медиа сам — добавьте его один раз:

1. Откройте Structure → Media types → Add media type (/admin/structure/media/add).
2. Введите название, например «Kinescope».
3. В поле Media source выберите Kinescope и сохраните тип.

Drupal создаст в типе медиа поле Kinescope URL. Поля для названия в форме нет: модуль подставляет название сам — из Kinescope API или в виде Kinescope: ID видео, если токен не задан.

Добавить видео в медиатеку можно двумя способами:

• Через раздел Media. Откройте Content → Media → Add media, выберите тип Kinescope, вставьте ссылку и сохраните.
• Из окна медиатеки. Если включён модуль ядра Media Library, видео добавляется прямо при выборе медиа: на вкладке типа Kinescope вставьте ссылку и нажмите Add. Если токен не задан, окно покажет предупреждение об этом.

Чтобы выводить видео из медиатеки в материалах, добавьте в тип материала поле Media и разрешите в нём ваш тип медиа Kinescope.

Данные видео в полях медиа

С токеном модуль получает данные видео, которые можно сохранить в поля медиа. Для этого в настройках типа медиа откройте блок Field mapping и сопоставьте данные с полями.

Постеры модуль сохраняет в папку kinescope_thumbs публичной файловой системы Drupal.

Видео во всплывающем окне

Модуль Kinescope Popup выводит вместо плеера постер со ссылкой. По клику плеер открывается в окне поверх страницы.

1. Включите Kinescope Popup.
2. Выберите формат вывода Kinescope popup:
   • для поля Kinescope в материале — в Manage display типа материала;
   • для видео из медиатеки — в Manage display типа медиа Kinescope, у поля Kinescope URL. Формат поля Media в материале менять не нужно.
3. В настройках формата задайте Link text — текст рядом с постером. По умолчанию — Play in popup.

Окно закрывается крестиком, клавишей Esc или щелчком за его пределами. При закрытии воспроизведение останавливается.

Ссылка на окно подписана ключом сайта и действует один час. Открыть окно могут роли с правом View published content.

Обновление с версий 1.1 и 1.2

В версиях 1.1.x и 1.2.x Kinescope был одним модулем. Начиная с 1.3 он разделён на четыре и работает только с Drupal 10 и 11.

1. Обновите модуль:

   composer require drupal/kinescope:^1.3
   

2. Запустите обновление базы данных: drush updb или страница /update.php. Обновление само включит Kinescope Player и Kinescope Media.

3. Проверьте способ встраивания на странице настроек Kinescope.

4. Очистите кеш:

   drush cr
   

Если что-то не работает

Плеер не показывается на сайте. Проверьте, не ограничено ли встраивание видео по доменам. Если ограничено, добавьте домен сайта в разрешённые — смотрите статью «Ограничение доступа к видео».

Название и описание не подтягиваются. Откройте Reports → Status report и проверьте строку Kinescope API token. Если токен задан, загляните в журнал Drupal: при ответе API 401 или 403 модуль записывает в канал kinescope предупреждение о проверке токена. Пока токен не работает, модуль выводит видео без данных из API.

Поле не принимает ссылку. Проверьте, что ссылка начинается с https://kinescope.io/ и в ней нет параметров после ?.

Что дальше?

После настройки модуля рекомендуем:

1. Ограничить доступ к видео — разрешите воспроизведение только на домене вашего сайта.
2. Настроить защиту контента — включите DRM-шифрование и водяные знаки.
3. Кастомизировать плеер — настройте внешний вид плеера под ваш бренд.
4. Изучить IFrame API — управляйте плеером из JavaScript.

Остались вопросы по работе модуля? Задайте их разработчикам в очереди задач проекта на drupal.org.