# Google Analytics: GA4 plugin The Google Analytics 4 (GA4) plugin allows you to track media content using the Google Analytics 4 service. It can help to measure traffic and engagement for video-on-demand (VOD) streams, live streams, and advertisements. The plugin leverages Google Analytics event tracking to record different playback related events. ## Before you start Before you start, we recommend reviewing these tagging resources from Google: * Introduction to tagging and the Google tag * Tagging for Google Analytics ## Install the plugin You can use the Google tag (gtag.js) or Google Tag Manager to load the Google Analytics library and install the G4 plugin. When using Google Tag Manager, additional steps may be required to set up and manage custom events. ### Install with gtag.js Follow these steps to install the GA4 plugin using the gtag.js method. For more, see the Set up gtag.js information from Google. 1. Add the following snippet to your site. It loads the `gtag.js` library, establishes the `GA_TRACKING_ID` as the default Google Analytics property ID, and sends a page view hit to Google Analytics. The snippet is best placed immediately after the opening `` HTML tag on every page you plan to measure. ```html ``` 2. Load the GA4 plugin and core player along with any other required plugins. If you would like to measure and track ads, make sure to also install the Wowza Flowplayer [Advertising plugin](/docs/wowza-flowplayer/plugins/advertising/). ```html ``` ### Install with Google Tag Manager If you're using Google Tag Manager or the `dataLayer` object, we suggest using the steps in this section. For more, see the Google Tag Manager webpage installation details from Google. 1. Add the following snippet to your site. It dynamically adds Google Tag Manager to the webpage by loading the external `gtm.js` script and specifies your Google Tag Manager container ID. The snippet is best placed immediately after the opening `` HTML tag on every page you plan to measure: ```html ``` 2. Load the GA4 plugin and core player along with any other required plugins. If you would like to measure and track ads, make sure to also install the Wowza Flowplayer [Advertising plugin](/docs/wowza-flowplayer/plugins/advertising/). ```html ``` ## Configure the plugin You can configure the GA4 plugin using the top-level configuration `ga` object. The following properties can be included in your configuration. | Property | Type | Description | | --- | --- | --- | | `data_layer_tracking` | *boolean* | Set to `true` to use the [dataLayer object](https://developers.google.com/tag-platform/tag-manager/web/datalayer) when tracking events. | | `ga_instances` | *string* | Add the Google Analytics tag IDs to track in this array. Required when using the gtag.js approach to set up Google Analytics. If not provided, the plugin pushes events to the [dataLayer object](https://developers.google.com/tag-platform/tag-manager/web/datalayer). | | `event_categories` | *string* | Use to optionally replace [default category names](/docs/wowza-flowplayer/plugins/google-analytics4/#event-categories) with custom values. If not set, the default values (live or videos) are detected by the player. Sent to Google Analytics as `event_category`. | | `event_actions` | *string* | Use to optionally replace [default action names](/docs/wowza-flowplayer/plugins/google-analytics4/#event-actions) with custom values. Sent to Google Analytics as `event_action`. | | `custom_data` | *string* | Add optional data or custom event parameters to be set and used on all existing events. | Info * The video title is used by default to send the `event_label` to Google Analytics. * If the plugin pushes events to the [dataLayer object](https://developers.google.com/tag-platform/tag-manager/web/datalayer), additional configuration may be required in Google Tag Manager. #### Example This code snippet provides an example of the top-level configuration using a `ga_instance` and Google tag ID. It's tailored more towards using the `gtag.js` JavaScript framework to send data from your site to Google's measurement products. ```js ga: { // set the data_layer_tracking property to true to leverage the dataLayer object data_layer_tracking: true, // ga_instances property is required when using the Google tag (gtag.js) method ga_instances: ["G-XXXXXXXXXX"], event_categories: { live: "my_live_value" }, event_actions: { live_start: "my_live_start_value" }, custom_data: { dimension0: "my_dimension_value", metric0: "my_metric_value" } } ``` info If Google tag IDs are omitted, we use the [dataLayer object](https://developers.google.com/tag-platform/tag-manager/web/datalayer), calling the `dataLayer.push()` method and a `flowplayer` event command to initiate the sending of events to Google Tag Manager. You can set up a [custom event trigger](https://support.google.com/tagmanager/answer/7679219) in Tag Manager to capture this `flowplayer` event. ## Set default values As described in this section, event categories and event actions have default values. It's possible to override these default values with a custom category or action in the configuration. See [Replace default values](/docs/wowza-flowplayer/plugins/google-analytics4/#replace-default-values) for additional information. ### Event categories Categories group objects that you want to analyze. In this case, they can help distinguish between live and video-on-demand events as you aggregate metrics. See the following table for the different event categories and their default values. | Event category | Default value | | --- | --- | | `live:` | "Live" | | `videos:` | "Videos" | ### Event actions Event actions help you define event types or interactions that you plan to measure for a particular web object. See the following table for the different event actions and their default values. Info **Preroll** ads display before a feature clip or live stream begins. On the other hand, **postroll** advertisements are shown after the media ends. Ads occurring between preroll and postroll advertisements are considered **midroll** events. | Event actions | Default value | Description | | --- | --- | --- | | `ad_break_completed` | "ad_break_completed" | Emitted after all ads of a preroll, midroll, or postroll are complete, regardless of the ad roll type. | | `ad_completed_preroll` | "ad_completed_preroll" | Emitted when each preroll ad is complete. | | `ad_completed_midroll` | "ad_completed_midroll" | Emitted when each midroll ad is complete. | | `ad_completed_postroll` | "ad_completed_postroll" | Emitted when each postroll ad is complete. | | `ad_skipped_preroll` | "ad_skipped_preroll" | Emitted when each preroll ad is skipped. | | `ad_skipped_midroll` | "ad_skipped_midroll" | Emitted when each midroll ad is skipped. | | `ad_skipped_postroll` | "ad_skipped_postroll" | Emitted when each postroll ad is skipped. | | `ad_start_preroll` | "ad_start_preroll" | Emitted when each preroll ad starts. | | `ad_start_midroll` | "ad_start_midroll" | Emitted when each midroll ad starts. | | `ad_start_postroll` | "ad_start_postroll" | Emitted when each postroll ad starts. | | `fullscreen_enter` | "fullscreen_enter" | Emitted when the player goes fullscreen. | | `fullscreen_exit` | "fullscreen_exit" | Emitted when the player exits fullscreen mode. | | `live_click_play` | "live_click_play" | Emitted when the user clicks to start live stream playback. | | `live_complete` | "live_complete" | Emitted when playback for a live stream is complete. | | `live_mute` | "live_mute" | Emitted when a live stream is muted. | | `live_pause` | "live_pause" | Emitted when a live stream is paused. | | `live_qualitychange` | "live_qualitychange" | Emitted for a live stream when the player changes quality. | | `live_ratechange` | "live_ratechange" | Emitted when the playback rate for a live stream changes. | | `live_resume` | "live_resume" | Emitted when a live stream resumes after a pause. | | `live_seeking` | "live_seeking" | Emitted for a live stream when the player is seeking. | | `live_start` | "live_start" | Emitted when a live stream is initially started. | | `live_unmute` | "live_unmute" | Emitted when a live stream is unmuted. | | `video_25_percent` | "video_25_percent" | Emitted when a VOD stream is 25 percent complete. | | `video_50_percent` | "video_50_percent" | Emitted when a VOD stream is 50 percent complete. | | `video_75_percent` | "video_75_percent" | Emitted when a VOD stream is 75 percent complete. | | `video_click_play` | "video_click_play" | Emitted when the user clicks to start VOD stream playback. | | `video_complete` | "video_complete" | Emitted when playback for a VOD stream is complete. | | `video_mute` | "video_mute" | Emitted when a VOD stream is muted. | | `video_pause` | "video_pause" | Emitted when a VOD stream is paused. | | `video_player_load` | "video_player_load" | Emitted when the player initially loads. | | `video_qualitychange` | "video_qualitychange" | Emitted for a VOD stream when the player changes quality. | | `video_ratechange` | "video_ratechange" | Emitted when the playback rate for a VOD stream changes. | | `video_resume` | "video_resume" | Emitted when a VOD stream resumes after a pause. | | `video_seeking` | "video_seeing" | Emitted for a VOD stream when the player is seeking. | | `video_start` | "video_start" | Emitted when a VOD stream is initially started or when its restarted after the initial start. | | `video_unmute` | "video_unmute" | Emitted when a VOD stream is unmuted. | ## Replace default values You can override the default values for event categories and event actions by customizing those values in your `ga` configuration. For example, use the following to set the `event_actions` property: ```js event_actions: { video_player_load: "my_custom_load_action" } ``` When replacing default values, all events you plan to track must be specified in the `ga` configuration. This includes event actions where you don't want to change the default value. ## Track ad positions By replacing the default value, you can track ad position and associated events. This capability only applies to `ad_start` events, such as `ad_start_preroll`, `ad_start_midroll`, and `ad_start_postroll`. Let's consider a scenario where you're trying to determine when the first, second, or third ad preroll has started. To do this, update your `ga` configuration to include `[x]` in your custom `ad_start_preroll` event action: ```js ga: { ga_instances: ["G-XXXXXXXXXX"], event_actions: { ad_start_preroll: "ad_start_preroll_[x]", } } ``` The GA4 plugin replaces the `[x]` and creates a sequence such as `ad_start_preroll_1`, `ad_start_preroll_2`, etc. This event sequence is sent to Google Analytics. ## Track a subset of events When using the GA4 plugin, you can specify which event actions to track. Otherwise, the player emits all of the event actions described in the [Event actions](/docs/wowza-flowplayer/plugins/google-analytics4/#event-actions) table. Add the event that should be tracked to the `ga` configuration and the plugin only considers those events. The following example shows how to only track these six start and complete events: ```js ga: { ga_instances: ["G-XXXXXXXXXX"], event_actions: { video_start: "video_start", video_complete: "video_complete", live_start: "live_start", ad_start_preroll: "ad_start_preroll", ad_start_midroll: "ad_start_midroll", ad_start_postroll: "ad_start_postroll" } } ```