# Google Analytics


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

This integration has `@beta` status. Follow the [player changelog](https://docs.kinescope.com/player-docs/changelog/).



The player can send viewing events to Google Analytics 4. Choose how you connect analytics to your site:

| Method | Best for |
| :--- | :--- |
| [Google Tag](#GASetup) | You connect gtag directly to your pages |
| [Google Tag Manager](#GTMSetup) | You already use GTM |

## Setup overview

1. Connect [Google Tag](#GASetup) or [GTM](#GTMSetup) to your site.
2. If the player runs in an `<iframe>` through [simple embedding](https://docs.kinescope.com/player-docs/embedding/simple-iframe-embed/) or the [IFrame API](https://docs.kinescope.com/player-docs/embedding/iframe-api/), add the [integration script](#PlayerSetupIframe).
3. [Create custom dimensions](#GA4CustomDimensions) in GA4 to filter reports by video.

## Integration script for iframe {#PlayerSetupIframe}

Player events occur inside the iframe. Add this script so the page can receive them:

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

Place the script **after** Google Tag or GTM. Without it, iframe events do not reach analytics.

## 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. Integration script after Google Tag. Required when the player is in an iframe -->
<script src="https://player.kinescope.io/latest/iframe.ga.js"></script>
```

Replace `G-XXXXXXXXXX` with your GA4 data stream ID.

## Google Tag Manager {#GTMSetup}

1. Download the [configuration file](https://player.kinescope.io/latest/gtm/workspace.json).
2. Import the file into GTM. Select **Merge** to keep your current container.
3. In the `GA4 – Event – Kinescope Video` tag, enter the data stream ID (`G-…`) used in Google Analytics.
4. Publish the container.
5. [Add custom definitions](#GA4CustomDimensions) in Google Analytics.

The file includes the `GA4 – Event – Kinescope Video` tag. It sends player actions such as `Play` and `Ended` with [video parameters](#Events).

### Page code example {#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. Integration script after GTM. Required when the player is in an iframe -->
<script src="https://player.kinescope.io/latest/iframe.ga.js"></script>
```

Replace `GTM-XXXXXXX` with your container ID. You do not need a separate gtag if GTM already sends data to GA4, as in the imported file.

Copy the snippet for users without JavaScript from Tag Manager. Paste it at the beginning of `<body>`.

## Events sent to GA4 {#Events}

The player sends these events by default:

| Event | When it fires |
| :--- | :--- |
| `Play` | Playback starts |
| `Ended` | Playback reaches the end |

If `settings.googleAnalytics.trigger` contains progress points, the player also sends events such as:

| Event | When it fires |
| :--- | :--- |
| `10 Percent Played`, `25 Percent Played`, … | The viewer reaches N percent |
| `60 Seconds Played`, `120 Seconds Played`, … | The viewer reaches N seconds |

Example with the [IFrame API](https://docs.kinescope.com/player-docs/embedding/iframe-api-create-player/#create):

```js
playerFactory.create('player', {
  url: 'https://kinescope.io/VIDEO_ID',
  settings: {
    googleAnalytics: {
      // Optional if the page already provides the measurement ID through gtag or 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, …
      },
    },
  },
})
```

You can set only `percentages`, only `timePoints`, or both arrays. Without `trigger`, the player sends only `Play` and `Ended`.

Event parameters:

| Parameter | Value |
| :--- | :--- |
| `video_id` | Kinescope video ID |
| `video_title` | Video title |
| `video_url` | Video URL |
| `video_duration` | Duration in seconds |
| `video_percent` | Viewing progress as a percentage |
| `video_current_time` | Current position in seconds |
| `video_seconds_played` | Number of seconds actually watched |
| `event_category` | Always `Video` |
| `external_id` | External ID, if set with `externalid` or `externalId` |

## Custom definitions in GA4 {#GA4CustomDimensions}

Create **custom dimensions** to filter reports by video.

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

In the **Event parameter** field, enter the technical name from the table, such as `video_id`. Do not enter a label such as “Video ID.”



1. In Google Analytics, go to **Admin** → **Custom definitions**.
2. Create event-scoped dimensions:

| Dimension name | Event parameter |
| :--- | :--- |
| Video ID | `video_id` |
| Video Title | `video_title` |
| Video URL | `video_url` |
| External ID | `external_id` |

Add numeric parameters such as `video_duration` and `video_percent` when needed.

## Next steps

- [Yandex Metrica](https://docs.kinescope.com/player-docs/yandex-metrika/) — send player events to Metrica
- [Simple iframe embedding](https://docs.kinescope.com/player-docs/embedding/simple-iframe-embed/) — configure `externalid`
- [IFrame API](https://docs.kinescope.com/player-docs/embedding/iframe-api/) — control the player and configure `settings.externalId`

