Analytics

Calls one function with an event each time something happens in playback. Play, seek, and pause the demo, and watch the events appear under it.

"use client";import { useMemo, useState } from "react";import { analytics } from "react-video-kit/analytics";import { VideoPlayer } from "react-video-kit/player";const oneDecimal = (_key: string, value: unknown) =>  typeof value === "number" ? Math.round(value * 10) / 10 : value;export default function Analytics() {  const [log, setLog] = useState<string[]>([]);  const plugins = useMemo(    () => [      analytics({        heartbeat: 10,        onEvent: (event) => setLog((lines) => [JSON.stringify(event, oneDecimal), ...lines].slice(0, 8)),      }),    ],    []  );  return (    <div className="flex flex-col gap-3">      <VideoPlayer src="/media/sample-720.mp4" poster="/media/poster.jpg" plugins={plugins} load="visible" />      <p className="text-sm text-current opacity-80">        Play, seek, and pause. Each event appears here as onEvent receives it, newest first, with a        heartbeat for every 10 seconds played.      </p>      <ol aria-label="Analytics events" className="flex min-h-44 flex-col gap-1 font-mono text-xs break-all text-current">        {log.length === 0 && <li className="opacity-80">No events yet. Press play.</li>}        {log.map((line, index) => (          <li key={index}>{line}</li>        ))}      </ol>    </div>  );}

Usage

import { analytics } from "react-video-kit/analytics";import { VideoPlayer } from "react-video-kit/player";const plugins = [analytics({ onEvent: (event) => console.log(event) })];<VideoPlayer src="/video.mp4" plugins={plugins} />;

heartbeat sets the seconds of playback between heartbeat events, and defaults to 30. 0 turns them off. progress sets the percentages that send a progress event, and defaults to 10, 25, 50, and 75:

analytics({ onEvent: (event) => console.log(event), heartbeat: 10, progress: [25, 50, 75, 90] });

Send events to a service

analytics({  onEvent(event) {    navigator.sendBeacon("/api/video-events", JSON.stringify(event));  },});

Google Analytics

googleAnalytics turns these events into the ones Google Analytics 4 uses for video, with the same names and parameters as its own measurement of embedded YouTube videos, so the two line up in your reports. Play this demo, and watch what would be sent. It contacts nobody, because send replaces the real call.

"use client";import { useMemo, useState } from "react";import { analytics } from "react-video-kit/analytics";import { googleAnalytics } from "react-video-kit/analytics/google";import { VideoPlayer } from "react-video-kit/player";export default function GoogleAnalytics() {  const [log, setLog] = useState<string[]>([]);  const plugins = useMemo(    () => [      analytics({        heartbeat: 0,        // `send` takes the place of gtag here, so this demo contacts nobody.        onEvent: googleAnalytics({          title: "View From A Blue Moon",          events: ["pause", "seek"],          send: (name, params) => setLog((lines) => [`${name} ${JSON.stringify(params)}`, ...lines].slice(0, 6)),        }),      }),    ],    []  );  return (    <div className="flex flex-col gap-3">      <VideoPlayer src="/media/sample-720.mp4?signed=secret-token" poster="/media/poster.jpg" plugins={plugins} load="visible" />      <ol aria-label="Events for Google Analytics" className="flex min-h-44 flex-col gap-1 font-mono text-xs break-all text-current">        {log.length === 0 && <li className="opacity-80">Nothing sent yet. Press play.</li>}        {log.map((line, index) => (          <li key={index}>{line}</li>        ))}      </ol>    </div>  );}

import { analytics } from "react-video-kit/analytics";import { googleAnalytics } from "react-video-kit/analytics/google";const plugins = [analytics({ onEvent: googleAnalytics({ title: "My video" }) })];

Each has video_current_time, video_duration, video_percent, video_provider, video_title, video_url, and visible, which says whether the page was showing. Analytics already has dimensions for video_provider, video_title, video_url, and visible. To report on the other three, register them as custom dimensions or metrics.

With gtag.js

Keep Google's usual snippet on the page. The plugin finds window.gtag, and never loads Google's script itself:

<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>

On a page with more than one Google tag, measurementId sends these events only to yours:

googleAnalytics({ measurementId: "G-XXXXXXXXXX", title: "My video" });

With Tag Manager

Without gtag, each event goes to window.dataLayer, as { event: "video_start", video_percent: 0, ... }. In Tag Manager, add a Custom Event trigger matching video_start|video_progress|video_complete as a regular expression, Data Layer Variables for the parameters you want, and a Google Analytics event tag using them.

If Tag Manager's own YouTube trigger or enhanced measurement also covers this page, that only watches embedded YouTube players, so it won't count these videos twice.

More events

Google has no names for these, so they're custom events, and off until you ask:

googleAnalytics({ events: ["pause", "seek", "rebuffer", "quality-change", "error"] });

error_code is one of the error codes. Google counts each parameter's value up to 100 characters, and each event up to 25 parameters, which these stay within apart from a long video_url.

Privacy and consent

• video_url has no query string or hash. Signed URLs carry tokens there. Change that with url, which can also leave the URL out:

  tsx

  googleAnalytics({ url: (source) => new URL(source, location.href).pathname });googleAnalytics({ url: () => undefined });

• video_error sends only the code, because a browser's message can include a URL.

• Nothing here sets or reads consent. That stays with your site and your consent banner. With Consent Mode, set your defaults before the Google tag loads, and these events follow them like any others:

  js

  gtag("consent", "default", { analytics_storage: "denied" });// Once the viewer chooses:gtag("consent", "update", { analytics_storage: "granted" });

To send to something else that takes these names, give it send:

googleAnalytics({ send: (name, params) => myAnalytics.track(name, params) });

Events

Every event has type, position, duration, percent, and source.

Behaviour

• Heartbeats count video played. Seeks and source changes add nothing and don't reset the count, so adding heartbeats up gives a close measure of how much was watched. It counts video time, so playing at 2× reaches the next heartbeat twice as fast.
• position comes from the player's clock when the event is sent, so seek reports where the seek landed.
• Dragging the timeline can send several seek events, one for each seek that finishes.
• A stall caused by a seek isn't counted as a rebuffer, including the moment after the seek finishes while playback picks back up.
• The end of the video sends ended without a pause.
• progress and complete follow playback, not position. Seeking past a mark doesn't send it, though playing through it later does. complete is true on ended when playback carried the video past its last mark, and has to be earned again on a second viewing.
• Progress reads the clock about once a second, and never writes to the store, so it adds no renders.
• onEvent runs inside the player's store update. Keep it quick, and don't let it throw, because that would stop the other subscribers in that update.

API

Options

State

This plugin has no state of its own.

Commands

This plugin has no commands of its own.

Google Analytics API

(options?: GoogleAnalyticsOptions) => (event: AnalyticsEvent) => void

GoogleAnalyticsExtra

GoogleAnalyticsParams