# google-analytics

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

Adds the Google Analytics 4 (GA4) [extension](https://videojs.org/docs/framework/html/guides/architecture) 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](https://videojs.org/docs/framework/html/guides/google-analytics) for how telemetry works.

## Import

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

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

Or load it from the [CDN](https://videojs.org/docs/framework/html/guides/cdn):

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

## Anatomy

```html
<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.

## See also

- [Google Analytics](https://videojs.org/docs/framework/html/guides/google-analytics): Configure GA4 video telemetry

---

HTML documentation: https://videojs.org/docs/framework/html/llms.txt
All documentation: https://videojs.org/llms.txt