Skip to content

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.6.0/extensions/google-analytics.js"></script>

Anatomy

<google-analytics></google-analytics>

Options

Attribute Property Description
metadata-* — Video metadata and custom dimensions. Drop the metadata- prefix and use kebab-case; each maps to a snake_case key (for example metadata-video-title → video_title)
— metadata Video metadata and custom dimensions reported with GA4 events. Overrides metadata-* attributes with the same key
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

Any number of metadata-* attributes can set dimensions without script. metadata remains a property when you need to pass an object or override attribute values, and onEvent is property-only. 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.

See also