ReferenceExtensions

google-analytics

Options for the Google Analytics 4 extension that tracks video engagement and playback events

Adds the Google Analytics 4 (GA4) extension to the player. It renders nothing — place it anywhere inside the player, and it follows whatever media the player attaches, dispatching standard GA4 Enhanced Measurement video events and playback interaction events to window.dataLayer. See Google Analytics for how telemetry works.

Import

pnpm add @videojs/html @videojs/google-analytics

import '@videojs/html/extensions/google-analytics';

Or load it from the CDN:

<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/extensions/google-analytics.js"></script>

Anatomy

<google-analytics></google-analytics>

Options

Attribute	Property	Description
—	`metadata`	Video metadata and custom dimensions reported with GA4 events
`data-layer-name`	`dataLayerName`	Name of the dataLayer array on `window`. Defaults to `'dataLayer'`
`disable-progress`	`disableProgress`	Disables 10%, 25%, 50%, and 75% progress milestones tracking
`debug`	`debug`	Logs telemetry events to the console. Defaults to `false`
—	`onEvent`	Callback to intercept dispatched events

metadata and onEvent take non-primitive values, so they’re properties only, with no matching attribute. Set them on the element, typed as the GoogleAnalyticsExtension class that @videojs/html/extensions/google-analytics exports.

Collection limits

Google Analytics 4 enforces collection limits on event parameters:

25 parameters per event: The extension sends 8 standard parameters (video_current_time, video_duration, video_percent, video_provider, video_stream_type, video_title, video_url, and visible), leaving room for up to 17 custom dimensions in metadata.
Parameter names: Up to 40 characters in length.
String values: Up to 100 characters in length.

Import

Anatomy

Options

Collection limits

See also