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.

Install the plugin

Follow these steps to install the GA4 plugin and other relevant libraries. In our example, we use the Google tag (gtag.js) approach to load the Google Analytics library. You can also utilize Google Tag Manager to achieve the same goal. However, when using Google Tag Manager, some additional steps may be required to set up and manage custom events.

Add the Google tag snippet to your website. The snippet is best placed immediately after the opening <head> HTML tag on every page you plan to measure.
Copy

Copied
```

<script async src="https://www.googletagmanager.com/gtag/js?id=TAG_ID"></script>
<script>
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag('js', new Date());

    gtag('config', 'TAG_ID');
</script>
```
This Google tag snippet 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.
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 .
Copy

Copied
```
<script src="//cdn.flowplayer.com/releases/native/3/stable/flowplayer.min.js"></script>
<script src="//cdn.flowplayer.com/releases/native/3/stable/plugins/ga4.min.js"></script>
```

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 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.
`event_categories`	string	Use to optionally replace default category names 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 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, additional configuration may be required in Google Tag Manager.

This code snippet provides an example of the top-level configuration using a ga_instance and Google tag ID:

Copy

Copied

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, 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 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 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_resume`	"live_resume"	Emitted when a live stream resumes after a pause.
`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_resume`	"video_resume"	Emitted when a VOD stream resumes after a pause.
`video_start`	"video_start"	Emitted when a VOD stream is initially started.
`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:

Copy

Copied

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:

Copy

Copied

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

Copy

Copied

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