# Модуль Kinescope для Drupal

> Модуль Kinescope для Drupal 10 и 11: установка, API-токен, способы встраивания плеера, поле Kinescope, видео в медиатеке и во всплывающем окне.

Источник: https://docs.kinescope.ru/integracii/integratsiya-s-drupal/
Обновлено: 2026-10-19

Если ваш сайт работает на Drupal, видео из Kinescope можно добавлять в материалы через модуль [Kinescope](https://www.drupal.org/project/kinescope). Вы вставляете ссылку на видео в поле, а модуль выводит на странице плеер Kinescope. Модуль поддерживает Drupal 10 и 11, текущая версия — **1.3.1**.

Модуль разрабатывают и поддерживают партнёры Kinescope. С вопросами и ошибками в его работе обращайтесь в [очередь задач проекта на drupal.org](https://www.drupal.org/project/issues/kinescope).

> **Информация:**
>
> Модуль не загружает видео в Kinescope. Загрузите ролик в [панель управления](https://app.kinescope.io), скопируйте ссылку на него и вставьте её в Drupal.

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

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

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

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

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

| Модуль | Что делает | Когда включать |
| :--- | :--- | :--- |
| **Kinescope** | Настройки и запросы к Kinescope API | Всегда |
| **Kinescope Player** | Тип поля Kinescope и вывод плеера | Всегда — без него видео не выводится |
| **Kinescope Media** | Источник Kinescope для медиатеки Drupal. Требует модуль ядра Media | Если храните видео в медиатеке |
| **Kinescope Popup** | Открытие плеера во всплывающем окне | Если нужен плеер поверх страницы |

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

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

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

## Установка

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

   ```bash
   composer require drupal/kinescope
   ```

2. В админке Drupal откройте **Extend** (`/admin/modules`).
3. Отметьте **Kinescope** и **Kinescope Player**. Если нужно, отметьте также **Kinescope Media** и **Kinescope Popup**.
4. Нажмите **Install**.

> **Информация:**
>
> Названия разделов и кнопок Drupal в статье приведены для английского интерфейса. Адреса вида `/admin/...` от языка интерфейса не зависят.

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

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

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

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

| | Без токена | С токеном |
| :--- | :--- | :--- |
| Плеер на странице | Да | Да |
| Название видео в медиатеке | `Kinescope: ID видео` | Название видео в Kinescope |
| Миниатюра в медиатеке | Постер по адресу `https://kinescope.io/ID/poster.webp` | Постер из данных видео в API |
| Описание, подзаголовок, длительность | Нет | Да |

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

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

1. В [Kinescope](https://app.kinescope.io) откройте **Настройки → API-токены** и создайте токен. Подробнее о токенах — в статье [«Общие правила API»](https://docs.kinescope.ru/instrukcii-dlya-razrabotchikov/api-obshchie-pravila/).
2. В Drupal на странице настроек Kinescope вставьте токен в поле **API token**.
3. Нажмите **Save configuration**.

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

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

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

> **Внимание:**
>
> API-токен даёт доступ к вашей рабочей зоне Kinescope. Не публикуйте его и не передавайте посторонним.

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

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

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

| Способ | Что выводит модуль |
| :--- | :--- |
| **Simple iframe embed** (по умолчанию) | Обычный `<iframe>` без JavaScript — [простое встраивание](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/prostoe-vstraivanie-iframe/) |
| **IFrame API (auto-connect)** | `<iframe>` с параметром `enableIframeApi` и скрипт IFrame API — [автоподключение к IFrame API](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api-avtopodklyuchenie/) |
| **Web Components (experimental)** | Элемент `<kinescope-iframe-player>` — [веб-компоненты](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/web-komponenty/) |

**IFrame API.** Модуль только подключает плеер к IFrame API. Код, который управляет плеером и обрабатывает его события, вы добавляете в тему сами — примеры есть в статье [«Автоподключение к IFrame API»](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api-avtopodklyuchenie/).

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

> **Внимание:**
>
> Веб-компоненты Kinescope — экспериментальная версия: их API может измениться.

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

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

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

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

| Параметр | По умолчанию | Описание |
| :--- | :--- | :--- |
| **Responsive** | Включён | Плеер занимает ширину контейнера с пропорциями 16:9 |
| **Width**, **Height** | 640 × 480 | Размер плеера в пикселях. Не действует, если включён **Responsive** |
| **Allow-list options** | `autoplay; fullscreen; picture-in-picture; encrypted-media; gyroscope; accelerometer; clipboard-write; screen-wake-lock;` | Значение атрибута `allow` у `<iframe>` |

> **Внимание:**
>
> Не убирайте значения из **Allow-list options**: без них могут не работать автозапуск, полноэкранный режим, Picture-in-Picture и DRM.

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

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** и сопоставьте данные с полями.

| Данные в Drupal | Что содержит |
| :--- | :--- |
| **Duration** | Длительность видео в секундах |
| **Description** | Описание видео |
| **Subtitles** | Подзаголовок видео — поле `subtitle` в API, а не файл субтитров |
| **Thumbnail URI** | Адрес сохранённого постера |
| **Video URL** | Ссылка на видео |

Постеры модуль сохраняет в папку `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. Обновите модуль:

   ```bash
   composer require drupal/kinescope:^1.3
   ```

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

   ```bash
   drush cr
   ```

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

**Плеер не показывается на сайте.** Проверьте, не ограничено ли встраивание видео по доменам. Если ограничено, добавьте домен сайта в разрешённые — смотрите статью [«Ограничение доступа к видео»](https://docs.kinescope.ru/zashita-kontenta/ogranichenie-dostupa-k-video/).

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

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

## Что дальше?

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

1. **[Ограничить доступ к видео](https://docs.kinescope.ru/zashita-kontenta/ogranichenie-dostupa-k-video/)** — разрешите воспроизведение только на домене вашего сайта.
2. **[Настроить защиту контента](https://docs.kinescope.ru/zashita-kontenta/)** — включите DRM-шифрование и водяные знаки.
3. **[Кастомизировать плеер](https://docs.kinescope.ru/videopleer-nastrojka-i-vstraivanie/kastomizatsiya-pleera/)** — настройте внешний вид плеера под ваш бренд.
4. **[Изучить IFrame API](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api/)** — управляйте плеером из JavaScript.

Остались вопросы по работе модуля? Задайте их разработчикам в [очереди задач проекта на drupal.org](https://www.drupal.org/project/issues/kinescope).