# Веб-компоненты Kinescope


Веб-компоненты позволяют вставить плеер тегом в HTML — без ручного `create()` и колбэков IFrame API. Сейчас доступен элемент `<kinescope-iframe-player>`.

> **Внимание:**

Экспериментальная версия: API может измениться. Следите за [изменениями плеера](https://docs.kinescope.ru/dokumentaciya-pleera/izmeneniya/).



Подробнее о технологии — на [MDN: Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components).

## Подключение

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

`https://player.kinescope.io/latest/elements/kinescope-iframe-player.js`

Атрибуты элемента совпадают с параметрами [простого встраивания](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/prostoe-vstraivanie-iframe/).

| Атрибут | Обязательный | Описание |
| :--- | :--- | :--- |
| `url` | да | URL видео |
| `id` | для конфига | Нужен, если настройки задаёте через `window.KinescopeIframePlayerConfig` |

При изменении `id`, `url` или `externalid` плеер пересоздаётся автоматически.

## Пример

```html
<script src="https://player.kinescope.io/latest/elements/kinescope-iframe-player.js"></script>

<script>
  window.KinescopeIframePlayerConfig = {
    ...window.KinescopeIframePlayerConfig,
    // ID элемента, к которому применяются настройки
    myplayer: {
      ui: { playbackRateButton: true },
    },
  }
</script>

<kinescope-iframe-player
  id="myplayer"
  url="https://kinescope.io/123456789"
  externalid="12345"
  autoplay
  style="background-color: green"
></kinescope-iframe-player>
```

## Конфигурация через KinescopeIframePlayerConfig

`window.KinescopeIframePlayerConfig` — объект вида «ID элемента → настройки». Настройки совпадают с [CreateOptions](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api-sozdanie-pleera/#create-options), кроме полей `url`, `size` и `settings`.

```ts
window.KinescopeIframePlayerConfig = {
  myplayer: {
    behavior: { /* … */ },
    ui: { /* … */ },
    theme: { /* … */ },
  },
}
```

## Методы

| Метод | Возвращает | Описание |
| :--- | :--- | :--- |
| <a id="getInstance"></a>`getInstance()` | `IframePlayerApi \| undefined` | [Объект управления плеером](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api-upravlenie-pleerom/). `undefined`, если плеер ещё не создан |
| <a id="waitInstance"></a>`waitInstance()` | `Promise<IframePlayerApi>` | Дождаться объекта управления, пока плеер создаётся |

## События

Подписка — через стандартные `addEventListener` / `removeEventListener`. Перечисление событий — в свойстве `Events` элемента. Большинство событий совпадает с [событиями IFrame API](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api-upravlenie-pleerom/#event-data).

Дополнительно:

| Событие | Описание |
| :--- | :--- |
| `Events.Created` | Плеер только что создан. Подпишитесь сразу после объявления элемента |

Данные события — в `event.detail`.

### Пример работы с API

```html
<kinescope-iframe-player
  id="myplayer"
  url="https://kinescope.io/VIDEO_ID"
></kinescope-iframe-player>
<script>
  const playerEl = document.getElementById('myplayer')

  // Вариант 1: событие создания
  playerEl.addEventListener(playerEl.Events.Created, () => {
    const player = playerEl.getInstance()
    player.setVolume(0.5)
  })

  // Вариант 2: ожидание через Promise
  ;(async () => {
    const player = await playerEl.waitInstance()
    player.on(player.Events.Playing, () => {
      console.log('Воспроизведение началось')
    })
  })()
</script>
```

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

- [IFrame API](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api/) — полный контроль из JavaScript
- [Простое встраивание](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/prostoe-vstraivanie-iframe/) — параметры URL
- [Библиотеки](https://docs.kinescope.ru/dokumentaciya-pleera/biblioteki/) — React, Vue, Angular