Events Reference

Complete reference for all events emitted by Ekoo widgets.

Events Table

Event Name	Category	Description	Stats Properties
`ekoo_widget_loaded`	Lifecycle	Widget initialized and visible	websiteId, productId
`ekoo_play`	Playback	User started audio playback	audioTitle, duration, productId
`ekoo_pause`	Playback	User paused audio	audioTitle, duration, playPercentage, productId
`ekoo_complete`	Playback	Audio finished playing	audioTitle, duration, playPercentage (100), productId
`ekoo_play_25`	Progress	Playback reached 25%	audioTitle, duration, playPercentage (25), productId
`ekoo_play_50`	Progress	Playback reached 50%	audioTitle, duration, playPercentage (50), productId
`ekoo_play_75`	Progress	Playback reached 75%	audioTitle, duration, playPercentage (75), productId
`ekoo_replay`	Playback	User replayed audio from beginning	audioTitle, duration, productId
`ekoo_next`	Navigation	User navigated to next audio (carousel)	audioTitle, productId
`ekoo_previous`	Navigation	User navigated to previous audio (carousel)	audioTitle, productId
`ekoo_error`	Error	Audio failed to load or play	productId, errorMessage

Event Object Structure

Every event callback receives an event object with the following shape:

EkooEvent interface

typescript

1// The event callback receives the full statistics body object:
2interface EkooEventBody {
3  // Session & context
4  sessionId: string;
5  source: string;          // Domain (e.g. "my-site.com")
6  href: string;            // Full page URL
7  path: string;            // URL pathname
8  device: string;          // "desktop", "mobile", "tablet"
9  ts: number;              // Timestamp (ms)
10
11  // Identification
12  websiteId: string;       // Your Ekoo website UUID
13  productRef: string;      // Product ID (from data attribute)
14  productId: string;       // Internal Ekoo product ID
15  audioId: string;         // Review/audio ID
16  locale: string;          // Configured locale
17  configVariant: string;   // Reference of the widget configuration applied to this widget
18
19  // Audio metadata
20  audioType: string;       // Audio type
21
22  // Event details (nested)
23  stats: {
24    type: string;          // Event name (see table below)
25    display: string;       // "widget"
26    widget: string;        // "standalone"
27    locale: string;        // Locale
28    reviews: string[];     // IDs of displayed reviews
29    review?: string;       // Current review ID (play/exit events)
30    source: string;        // Domain
31    reached?: number;      // Progress ratio (play events: 0, 0.25, 0.5, 0.75, 1)
32  };
33}

The stats object contains event-specific data. Not all properties are present on every event — for instance, errorMessage is only included with ekoo_error events.

Listening to Events

Via HTML Attribute

Use the data-ekoo-on-event attribute to specify a global callback function:

Callback via data-ekoo-on-event

html

1<script>
2  // The callback receives a single argument: the full stats body
3  function onEkooEvent(data) {
4    switch (data.stats.type) {
5      case 'printed':
6        console.log('Widget displayed for product', data.productRef);
7        break;
8      case 'played-0':
9        console.log('Playback started — review:', data.audioId);
10        break;
11      case 'played-100':
12        console.log('Audio fully listened!');
13        break;
14    }
15  }
16</script>
17
18<ekoo-widget
19  data-ekoo="YOUR_WEBSITE_ID"
20  data-ekoo-product-id="YOUR_PRODUCT_ID"
21  data-ekoo-on-event="onEkooEvent"
22></ekoo-widget>

Via data-ekoo-on-event with GTM

The same data-ekoo-on-event attribute can be used to push events to the GTM dataLayer:

Callback with GTM dataLayer

javascript

1<script>
2  function onEkooEvent(data) {
3    // Push to GTM dataLayer
4    window.dataLayer = window.dataLayer || [];
5    window.dataLayer.push({
6      event: 'ekoo_' + data.stats.type.replace('-', '_'),
7      ekoo_event_type: data.stats.type,
8      ekoo_widget_type: data.stats.widget,
9      ekoo_product_id: data.productRef,
10      ekoo_review_id: data.audioId,
11      ekoo_locale: data.locale,
12      ekoo_source: data.source,
13      ekoo_reached: data.stats.reached || null
14    });
15  }
16</script>
17
18<ekoo-widget
19  data-ekoo="YOUR_WEBSITE_ID"
20  data-ekoo-product-id="YOUR_PRODUCT_ID"
21  data-ekoo-on-event="onEkooEvent"
22></ekoo-widget>

💡

Progress Events

Progress events (ekoo_play_25, ekoo_play_50, ekoo_play_75) fire exactly once per playback session. Replaying the audio resets the progress tracker.

Complete Example: GA4 Tracking via GTM

Full GA4/GTM integration

html

1<script>
2  // 1. Initialize the dataLayer
3  window.dataLayer = window.dataLayer || [];
4
5  // 2. Define the event callback (receives a single data object)
6  function onEkooEvent(data) {
7    window.dataLayer.push({
8      event: 'ekoo_' + data.stats.type.replace('-', '_'),
9      ekoo_product_id: data.productRef,
10      ekoo_review_id: data.audioId,
11      ekoo_locale: data.locale,
12      ekoo_reached: data.stats.reached || null
13    });
14  }
15</script>
16
17<!-- 3. Ekoo script -->
18<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>
19
20<!-- 4. Container -->
21<ekoo-widget
22  data-ekoo="YOUR_WEBSITE_ID"
23  data-ekoo-product-id="YOUR_PRODUCT_ID"
24  data-ekoo-on-event="onEkooEvent"
25></ekoo-widget>

Related Resources

Analytics Overview — Track and analyze widget engagement
JavaScript API — Programmatic widget control functions