Configuring a new programmatic Google Analytics custom event

We have configured Google Tag Manager (GTM) on our sites. The docs for using Google Analytics v4 (GA4) are confusing and often in conflict. This document will walk through adding a programmatic event in the code and getting it to show up in GA4.

This document does not cover adding a GTM trigger non-programmatically (e.g. tracking button clicks by existing button ID), which is the process non-engineers should try to follow to gather analytics.

Adding the event in code

Define your custom event name and parameters (note the limits and restrictions applied by GTM/GA4) and invoke them in your code by calling

window.dataLayer.push({ 
  "event": "my_event_name",
  "event_custom_property_1": "foo"
})

Depending on the project, we may already have utilities to do this, so look for those or reach out to a teammate to identify those before writing new code.

Add a custom trigger in GTM

We have to configure a trigger in GTM with the custom event. To do that,

Go to GTM → Triggers → New
Choose “Custom Event”
Ensure the “Event name” exactly matches the event name that you wish to match. Set up the trigger to fire when your event equals your programmatic event and save it with a friendly name.

Example GTM trigger for a new custom event

Configure sending tag data to Google Analytics

To see the custom event data in GA4, you need to configure GTM to send events when the trigger is fired. To do this in GTM:

Go to GTM → Tags → New
Under “Tag Configuration” select Google Analytics → GA4 Event
For “Measurement ID”, you can select the constant that refers to the GA4 (not GTM!) measurement ID for Synapse
For “Event Name”, enter the GA4 event name. This is probably the same event name that you used when setting up the GTM trigger
Under “Triggering”, select the trigger you created in the previous step.

Example GTM tag to configure sending data to GA4

Mapping event parameters

To ensure your custom event parameters are transmitted to GA4, you also need to map each parameter in each tag.

For example, in a “Search Query Submitted” tag, we want to include a “query_term” custom event parameter. To do so:

Edit your tag and find “Event Parameters” and click “Add parameter”
For the “Event Parameter” value, enter the parameter name as you expect it to appear in GA4. In this case, we want this to also be “query_term”, but it does not have to match.
For “Value”, we want to create (or reuse) a Data Layer Variable, so click the Data Block icon. If a Data Layer Variable matching your custom event data exists, use that. Otherwise, click “+” in the top right to create a new variable.
(If creating a new variable) Select “Data Layer Variable” to tell GTM that this event parameter will come from the data passed to the dataLayer.
(If creating a new variable) For “Data Layer Variable Name”, enter the key of the object in the custom event data. In our case, this will be “query_term”. Click “Save”. As a convention, save this as “DL - <variable_name>”.

Once all of your parameters have been added, you can save the changes to your tag.

Verify triggers & tags are invoked

If you have a site with your custom events running locally (e.g. SWC on 127.0.0.1:8888) you can click “Preview” in GTM and enter the local address to open the site with GTM debugging attached. In the debug window, you can see when your custom events are triggered and verify that they are captured in GTM and sent to GA4.

Publish Changes

Ensure you publish your changes so the live production site is affected.