# Google Analytics


> **Информация:**

Интеграция в статусе `@beta`. Следите за [изменениями плеера](https://docs.kinescope.ru/dokumentaciya-pleera/izmeneniya/).



Плеер может отправлять события просмотра в Google Analytics 4. Выберите способ подключения аналитики на сайте:

| Способ | Когда подходит |
| :--- | :--- |
| [Google Tag](#GASetup) | gtag подключён напрямую на страницах |
| [Google Tag Manager](#GTMSetup) | Уже используете GTM |

## Что нужно сделать

1. Подключите на сайте [Google Tag](#GASetup) или [GTM](#GTMSetup).
2. Если плеер во `<iframe>` ([простое встраивание](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/prostoe-vstraivanie-iframe/) или [IFrame API](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api/)) — добавьте [скрипт интеграции](#PlayerSetupIframe).
3. [Создайте пользовательские измерения](#GA4CustomDimensions) в GA4, чтобы фильтровать отчёты по видео.

## Скрипт интеграции для iframe {#PlayerSetupIframe}

События плеера возникают внутри iframe. Чтобы страница их «увидела», подключите:

`https://player.kinescope.io/latest/iframe.ga.js`

Ставьте скрипт **после** Google Tag или GTM. Без него события из iframe в аналитику не попадут.

## Google Tag {#GASetup}

```html
<!-- 1. Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
  window.dataLayer = window.dataLayer || []
  function gtag() {
    dataLayer.push(arguments)
  }
  gtag('js', new Date())
  gtag('config', 'G-XXXXXXXXXX')
</script>

<!-- 2. Скрипт интеграции (после Google Tag; нужен, если плеер во iframe) -->
<script src="https://player.kinescope.io/latest/iframe.ga.js"></script>
```

Замените `G-XXXXXXXXXX` на идентификатор потока данных GA4.

## Google Tag Manager {#GTMSetup}

1. Скачайте [готовый файл настроек](https://player.kinescope.io/latest/gtm/workspace.json).
2. В GTM импортируйте файл. Выберите **объединение**, чтобы не затереть текущий контейнер.
3. В теге `GA4 – Event – Kinescope Video` укажите тот же идентификатор потока (`G-…`), что в Google Analytics.
4. Опубликуйте контейнер.
5. [Добавьте пользовательские определения](#GA4CustomDimensions) в Google Analytics.

В файле уже есть тег `GA4 – Event – Kinescope Video`: он отправляет действия плеера (`Play`, `Ended` и другие) вместе с [параметрами видео](#Events).

### Пример кода на странице {#GTMExample}

```html
<!-- 1. Google Tag Manager -->
<script>
  ;(function (w, d, s, l, i) {
    w[l] = w[l] || []
    w[l].push({ 'gtm.start': new Date().getTime(), event: 'gtm.js' })
    var f = d.getElementsByTagName(s)[0],
      j = d.createElement(s),
      dl = l != 'dataLayer' ? '&l=' + l : ''
    j.async = true
    j.src = 'https://www.googletagmanager.com/gtm.js?id=' + i + dl
    f.parentNode.insertBefore(j, f)
  })(window, document, 'script', 'dataLayer', 'GTM-XXXXXXX')
</script>

<!-- 2. Скрипт интеграции (после GTM; нужен, если плеер во iframe) -->
<script src="https://player.kinescope.io/latest/iframe.ga.js"></script>
```

Замените `GTM-XXXXXXX` на ID контейнера. Отдельный gtag на странице не нужен, если отправка в GA4 уже настроена внутри GTM (как в импортированном файле).

Фрагмент для пользователей без JavaScript скопируйте из интерфейса Tag Manager и вставьте в начало `<body>`.

## Какие события отправляются {#Events}

По умолчанию:

| Событие | Когда |
| :--- | :--- |
| `Play` | Начало просмотра |
| `Ended` | Досмотр до конца |

Если в `settings.googleAnalytics.trigger` заданы точки прогресса, дополнительно уходят, например:

| Событие | Когда |
| :--- | :--- |
| `10 Percent Played`, `25 Percent Played`, … | Досмотрено N процентов |
| `60 Seconds Played`, `120 Seconds Played`, … | Досмотрено N секунд |

Пример через [IFrame API](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api-sozdanie-pleera/#create):

```js
playerFactory.create('player', {
  url: 'https://kinescope.io/VIDEO_ID',
  settings: {
    googleAnalytics: {
      // необязательно, если measurement ID уже задан через gtag/GTM на странице
      // measurementId: 'G-XXXXXXXXXX',
      trigger: {
        percentages: [10, 25, 50, 75, 95], // → 10 Percent Played, 25 Percent Played, …
        timePoints: [60, 120, 300, 600], // → 60 Seconds Played, 120 Seconds Played, …
      },
    },
  },
})
```

Можно указать только `percentages`, только `timePoints` или оба массива. Без `trigger` уходят только `Play` и `Ended`.

Параметры события:

| Параметр | Значение |
| :--- | :--- |
| `video_id` | ID видео в Kinescope |
| `video_title` | Название |
| `video_url` | Ссылка на видео |
| `video_duration` | Длительность, сек |
| `video_percent` | Прогресс просмотра, % |
| `video_current_time` | Текущая позиция, сек |
| `video_seconds_played` | Сколько секунд реально смотрели |
| `event_category` | Всегда `Video` |
| `external_id` | Внешний ID, если задан (`externalid` / `externalId`) |

## Пользовательские определения в GA4 {#GA4CustomDimensions}

Чтобы в отчётах фильтровать по видео, создайте **пользовательские измерения**.

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

В поле **Параметр события** укажите техническое имя из таблицы (`video_id`), а не подпись вроде «Video ID».



1. Google Analytics → **Администратор** → **Пользовательские определения**.
2. Создайте измерения с областью **событие**:

| Название | Параметр события |
| :--- | :--- |
| Video ID | `video_id` |
| Video Title | `video_title` |
| Video URL | `video_url` |
| External ID | `external_id` |

Числовые параметры (`video_duration`, `video_percent` и другие) добавляйте по необходимости.

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

- [Яндекс Метрика](https://docs.kinescope.ru/dokumentaciya-pleera/yandex-metrika/) — события плеера в Метрику
- [Простое встраивание](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/prostoe-vstraivanie-iframe/) — параметр `externalid`
- [IFrame API](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api/) — управление плеером и `settings.externalId`

