# Kinescope Web Components


Web Components let you embed the player with an HTML tag. You do not need to call `create()` or use IFrame API callbacks. The `<kinescope-iframe-player>` element is currently available.

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

This feature is experimental, so its API may change. Follow the [player changelog](https://docs.kinescope.com/player-docs/changelog/).



For more information about the technology, see [MDN: Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components).

## Connect the component

Load this script before using the component:

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

The element attributes match the parameters for a [simple iframe embed](https://docs.kinescope.com/player-docs/embedding/simple-iframe-embed/).

| Attribute | Required | Description |
| :--- | :--- | :--- |
| `url` | yes | Video URL |
| `id` | for configuration | Required when you set options through `window.KinescopeIframePlayerConfig` |

The player is recreated automatically when `id`, `url`, or `externalid` changes.

## Example

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

<script>
  window.KinescopeIframePlayerConfig = {
    ...window.KinescopeIframePlayerConfig,
    // ID of the element that receives these settings
    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>
```

## Configure KinescopeIframePlayerConfig

`window.KinescopeIframePlayerConfig` maps element IDs to their settings. The settings match [CreateOptions](https://docs.kinescope.com/player-docs/embedding/iframe-api-create-player/#create-options), except for the `url`, `size`, and `settings` fields.

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

## Methods

| Method | Returns | Description |
| :--- | :--- | :--- |
| <a id="getInstance"></a>`getInstance()` | `IframePlayerApi \| undefined` | The [player control object](https://docs.kinescope.com/player-docs/embedding/iframe-api-control-player/), or `undefined` if the player has not been created |
| <a id="waitInstance"></a>`waitInstance()` | `Promise<IframePlayerApi>` | Wait for the control object while the player is being created |

## Events

Subscribe with the standard `addEventListener` and `removeEventListener` methods. The event enumeration is available in the element's `Events` property. Most events match the [IFrame API events](https://docs.kinescope.com/player-docs/embedding/iframe-api-control-player/#event-data).

The component also provides this event:

| Event | Description |
| :--- | :--- |
| `Events.Created` | The player was just created. Subscribe immediately after declaring the element |

Event data is available in `event.detail`.

### API example

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

  // Option 1: creation event
  playerEl.addEventListener(playerEl.Events.Created, () => {
    const player = playerEl.getInstance()
    player.setVolume(0.5)
  })

  // Option 2: wait with a Promise
  ;(async () => {
    const player = await playerEl.waitInstance()
    player.on(player.Events.Playing, () => {
      console.log('Playback started')
    })
  })()
</script>
```

## Next steps

- [IFrame API](https://docs.kinescope.com/player-docs/embedding/iframe-api/) — full control from JavaScript
- [Simple iframe embed](https://docs.kinescope.com/player-docs/embedding/simple-iframe-embed/) — URL parameters
- [Libraries](https://docs.kinescope.com/player-docs/libraries/) — React, Vue, and Angular