Référence des événements

Référence complète de tous les événements émis par les widgets Ekoo.

Tableau des événements

Nom de l'événement	Catégorie	Description	Propriétés des statistiques
`ekoo_widget_loaded`	Cycle de vie	Widget initialisé et visible	websiteId, productId
`ekoo_play`	Lecture	L'utilisateur a démarré la lecture audio	audioTitle, duration, productId
`ekoo_pause`	Lecture	L'utilisateur a mis l'audio en pause	audioTitle, duration, playPercentage, productId
`ekoo_complete`	Lecture	L'audio a fini de jouer	audioTitle, duration, playPercentage (100), productId
`ekoo_play_25`	Progression	La lecture a atteint 25%	audioTitle, duration, playPercentage (25), productId
`ekoo_play_50`	Progression	La lecture a atteint 50%	audioTitle, duration, playPercentage (50), productId
`ekoo_play_75`	Progression	La lecture a atteint 75%	audioTitle, duration, playPercentage (75), productId
`ekoo_replay`	Lecture	L'utilisateur a relu l'audio depuis le début	audioTitle, duration, productId
`ekoo_next`	Navigation	L'utilisateur a navigué vers l'audio suivant (carrousel)	audioTitle, productId
`ekoo_previous`	Navigation	L'utilisateur a navigué vers l'audio précédent (carrousel)	audioTitle, productId
`ekoo_error`	Erreur	L'audio n'a pas pu se charger ou jouer	productId, errorMessage

Structure de l'objet événement

Chaque callback d'événement reçoit un objet événement avec la forme suivante :

Interface EkooEvent

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}

L'objet statscontient des données spécifiques à l'événement. Toutes les propriétés ne sont pas présentes sur chaque événement — par exemple, errorMessage est seulement inclus avec les événements ekoo_error.

Écouter les événements

Via l'attribut HTML

Utilisez l'attribut data-ekoo-on-event pour spécifier une fonction callback globale :

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 avec GTM

Le même attribut data-ekoo-on-event peut être utilisé pour pousser les événements vers le dataLayer GTM :

Callback avec 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>

💡

Événements de progression

Les événements de progression (ekoo_play_25, ekoo_play_50, ekoo_play_75) se déclenchent exactement une fois par session de lecture. Rejouer l'audio remet le tracker de progression à zéro.

Exemple complet : Suivi GA4 via GTM

Intégration complète GA4/GTM

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>

Ressources associées

Vue d'ensemble Analytics — Suivre et analyser l'engagement du widget
API JavaScript — Fonctions de contrôle programmatique du widget