DataLayer Integration

Push Ekoo events to the dataLayer for use in GTM and GA4.

What is the dataLayer?

The dataLayer is a standard JavaScript array that Google Tag Manager reads to detect and process events. Each call to dataLayer.push() adds an object to this array; GTM automatically intercepts each addition and triggers the associated tags.

This is the standard mechanism for connecting your site with GTM and, by extension, with GA4 and all your measurement tools.

Initialize the dataLayer

Before pushing events, make sure the array exists. This line can be placed anywhere before your first push():

1window.dataLayer = window.dataLayer || [];

Push all events

The simplest approach: every Ekoo event is sent to the dataLayer. You can filter on the GTM side if needed.

1function onEkooEvent(data) {
2  window.dataLayer = window.dataLayer || [];
3  window.dataLayer.push({
4    event: 'ekoo_' + data.stats.type.replace('-', '_'),
5    ekoo_event_type: data.stats.type,
6    ekoo_widget_type: data.stats.widget,
7    ekoo_review_id: data.audioId,
8    ekoo_product_id: data.productRef,
9    ekoo_source: data.source,
10    ekoo_reached: data.stats.reached || null
11  });
12}

Push only certain events

If you want to limit the volume of data sent to GA4, filter directly in your callback. The example below only pushes played-0 (play start) and played-100 (complete listen):

1function onEkooEvent(data) {
2  const tracked = ['played-0', 'played-100'];
3  if (!tracked.includes(data.stats.type)) return;
4
5  window.dataLayer = window.dataLayer || [];
6  window.dataLayer.push({
7    event: 'ekoo_' + data.stats.type.replace('-', '_'),
8    ekoo_event_type: data.stats.type,
9    ekoo_widget_type: data.stats.widget
10  });
11}

Event structure in the dataLayer

Here is the detail of each property pushed to the dataLayer:

Verify events in the console

Open your browser's developer console (F12) and run the following command to display only Ekoo events present in the dataLayer:

1console.table(window.dataLayer.filter(e => e.event?.startsWith('ekoo_')));

You should see a table with each pushed event, its properties, and their values. This is the quickest way to validate your integration before moving to GTM.

Naming conventions

Follow these three rules to ensure GA4 compatibility and report readability:

1. Always prefix with ekoo_ to distinguish Ekoo events from your other events
2. Use underscores (_) and never hyphens — GA4 rejects event names containing hyphens
3. Name properties consistently: ekoo_event_type, ekoo_widget_type, ekoo_review_id, ekoo_source