Events and Analytics

Measure the impact of your audio content on engagement and conversion.

Philosophy

Ekoo does not use any cookies and does not track your visitors. The widget does not inject any third-party tracker and does not collect any personal browsing data.

However, the widget emits client-side events at every key interaction (display, play, progress, listen complete). You can capture these events and send them to your own analytics stack (GA4, Matomo, Mixpanel, Piano…) to precisely measure the impact of audio on your conversion rates.

How It Works

Add the data-ekoo-on-event attribute to your widget div. Its value is the name of a global JavaScript function that you define. This function is called on every widget event and receives a stats object containing all interaction details.

Available Events

• printed — the widget is displayed on the page
• played-0 — audio playback starts
• played-25 — 25% of the content has been listened to
• played-50 — 50% of the content has been listened to
• played-75 — 75% of the content has been listened to
• played-100 — full listen (triggers at 98% progress)

Structure of the Received Object

Your callback receives an object with the following structure:

1{
2  "sessionId": "abc-123-...",
3  "source": "my-site.com",
4  "href": "https://my-site.com/products/widget",
5  "path": "/products/widget",
6  "websiteId": "YOUR_WEBSITE_ID",
7  "productRef": "PRODUCT_123",        // product ID from data attribute
8  "productId": "internal-id",          // internal Ekoo product ID
9  "audioId": "rev_abc",                // review/audio ID
10  "locale": "fr",
11  "device": "desktop",
12  "ts": 1710000000000,
13  "stats": {
14    "type": "played-25",               // event name
15    "reached": 0.25,                   // progress ratio (play events only)
16    "display": "widget",
17    "widget": "standalone",
18    "locale": "fr",
19    "reviews": ["rev_abc"],
20    "review": "rev_abc",
21    "source": "my-site.com"
22  }
23}

Setup

Step 1 — Add the Attribute to Your Widget

Add data-ekoo-on-event="onEkooEvent" to the widget div. The value must match the exact name of your callback function.

Step 2 — Define the Callback Function

Declare your function before the Ekoo script loads. It will be called automatically on every widget event.

Step 3 — Send Data to Your Analytics

Inside your callback, push the data to the dataLayer (for GTM/GA4) or call your analytics tool's API directly.

1<ekoo-widget
2  data-ekoo="YOUR_WEBSITE_ID"
3  data-ekoo-product-id="PRODUCT_123"
4  data-ekoo-locale="fr"
5  data-ekoo-on-event="onEkooEvent"
6></ekoo-widget>
7
8<script>
9function onEkooEvent(data) {
10  console.log('[Ekoo]', data.stats.type, data);
11
12  window.dataLayer = window.dataLayer || [];
13  window.dataLayer.push({
14    event: 'ekoo_' + data.stats.type.replace('-', '_'),
15    ekoo_event_type: data.stats.type,
16    ekoo_widget_type: data.stats.widget,
17    ekoo_product_id: data.productRef,
18    ekoo_source: data.source
19  });
20}
21</script>
22
23<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>

Quick Event Reference

Naming Best Practices

To ensure GA4 compatibility and facilitate analysis, apply these conventions consistently:

• Prefix all your events with ekoo_
• Replace hyphens with underscores — GA4 does not accept hyphens in event names

Which Event to Use for Which Measurement?

• printed → measure widget visibility on your pages
• played-0 → measure audio play rate (listening intent)
• played-25 / played-50 → measure engagement during listening
• played-100 → measure full listen — ideal for correlating with conversion

Integration Guides

• GA4 + Google Tag Manager Integration — complete step-by-step guide to measure audio impact on conversion
• DataLayer Integration — push events to the dataLayer for GTM, GA4, or any other tool
• Kameleoon Integration — measure audio starts with a Kameleoon custom goal