Google Analytics
@beta status. Follow the player changelog
.The player can send viewing events to Google Analytics 4. Choose how you connect analytics to your site:
| Method | Best for |
|---|---|
| Google Tag | You connect gtag directly to your pages |
| Google Tag Manager | You already use GTM |
Setup overview
- Connect Google Tag or GTM to your site.
- If the player runs in an
<iframe>through simple embedding or the IFrame API , add the integration script . - Create custom dimensions in GA4 to filter reports by video.
Integration script for iframe
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
<!-- 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
- Download the configuration file .
- Import the file into GTM. Select Merge to keep your current container.
- In the
GA4 – Event – Kinescope Videotag, enter the data stream ID (G-…) used in Google Analytics. - Publish the container.
- Add custom definitions in Google Analytics.
The file includes the GA4 – Event – Kinescope Video tag. It sends player actions such as Play and Ended with video parameters
.
Page code example
<!-- 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
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 :
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
Create custom dimensions to filter reports by video.
video_id. Do not enter a label such as “Video ID.”- In Google Analytics, go to Admin → Custom definitions.
- 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 — send player events to Metrica
- Simple iframe embedding
— configure
externalid - IFrame API
— control the player and configure
settings.externalId