API JavaScript

Ekoo expose des fonctions JavaScript globales pour le contrôle programmatique du widget. Utilisez-les quand vous avez besoin de plus que les seuls attributs data.

ekooLoad()

Initialise tous les éléments <ekoo-widget> sur la page. Cette fonction est appelée automatiquement quand le script Ekoo se charge, mais vous pouvez l'invoquer manuellement quand des widgets sont ajoutés au DOM dynamiquement.

Signature

1window.ekooLoad(): void

Utilisation

Exemples d'ekooLoad

javascript

1// Initialize all widgets on the page
2window.ekooLoad();
3
4// Typically called:
5// - After dynamically adding widget containers to the DOM
6// - On SPA route change (after DOM update)
7// - After script lazy-loading

Quand l'utiliser : Après avoir ajouté dynamiquement des éléments <ekoo-widget> au DOM — par exemple, dans une application single-page après un changement de route ou après avoir injecté du markup de widget via JavaScript.

ekooUnload()

Détruit toutes les instances de widget actives. Supprime les écouteurs d'événements et nettoie les ressources associées à chaque widget Ekoo sur la page.

Signature

1window.ekooUnload(): void

Utilisation

Nettoyage

javascript

1// Remove all widgets — always call on unmount in a SPA
2window.ekooUnload();

Quand l'utiliser : Pendant les transitions de page SPA, le démontage de composant, ou tout scénario où vous devez détruire des widgets et libérer leurs ressources avant de naviguer ailleurs.

ekooReload()

Méthode de commodité qui appelle ekooUnload() suivi de ekooLoad(). Réinitialise tous les widgets sur la page avec leurs attributs actuels.

Signature

1window.ekooReload(): void

Utilisation

Rechargement après changement de produit

javascript

1// Update the displayed product
2const container = document.querySelector('[data-ekoo-product-id]');
3container.setAttribute('data-ekoo-product-id', 'new-product');
4
5// Unload + reload in one call
6window.ekooReload();

Quand l'utiliser : Après avoir changé un ID de produit, basculé de locale, ou tout changement de contexte qui nécessite que les widgets se rafraîchissent avec de nouvelles données.

ekooOptions

Un objet de configuration global qui définit les valeurs par défaut pour tous les widgets Ekoo sur la page. Doit être défini avant que le script Ekoo ne se charge.

Propriétés

Propriété	Type	Description
`websiteId`	string	Votre UUID de site Ekoo
`widgets`	Array	Tableau de configurations de widget (voir structure ci-dessous)
`widgets[].nodeId`	string \| () => HTMLElement	ID de l'élément cible ou fonction retournant l'élément
`widgets[].productId`	string \| () => string	ID du produit ou fonction retournant l'ID
`widgets[].locale`	string \| () => string	Locale optionnelle (code ISO 639-1)

Exemple complet d'ekooOptions

javascript

1// --- Method 1: HTML data attributes (recommended) ---
2// Configuration is set directly on the container element.
3// The websiteId is the value of data-ekoo.
4
5<ekoo-widget
6  data-ekoo="YOUR_WEBSITE_ID"
7  data-ekoo-product-id="YOUR_PRODUCT_ID"
8  data-ekoo-locale="fr"
9  data-ekoo-variant="WIDGET_CONFIG_REF"
10  data-ekoo-on-event="onEkooEvent"
11  data-ekoo-always-open="true"
12  data-ekoo-direction="reverse"
13  data-ekoo-scale="1.2"
14  data-ekoo-animation="pulse"
15  data-ekoo-show-transcript="true"
16  data-ekoo-show-speed-button="true"
17  data-shadow-mode="open"
18></ekoo-widget>
19
20// --- Method 2: JavaScript configuration (for dynamic insertion) ---
21
22window.ekooOptions = {
23  websiteId: "YOUR_WEBSITE_ID",
24  widgets: [
25    {
26      nodeId: "container-id",          // or: () => document.querySelector('.my-class')
27      productId: "YOUR_PRODUCT_ID",    // or: () => getProductId()
28      locale: "fr"                     // or: () => getUserLocale()
29    }
30  ]
31};

Structure EkooOptions

Interface window.ekooOptions

typescript

1// window.ekooOptions structure
2interface EkooOptions {
3  websiteId: string;               // Your Ekoo website UUID
4  widgets: Array<{
5    nodeId: string | (() => HTMLElement);  // Target element ID or function returning element
6    productId: string | (() => string);    // Product ID or function returning it
7    locale?: string | (() => string);      // Optional locale ("fr", "en", "auto")
8  }>;
9}
10
11// HTML data attributes (on each widget container):
12// Core
13//   data-ekoo="WEBSITE_ID"                       — required, your website UUID
14//   data-ekoo-product-id="PRODUCT_ID"             — required, product identifier
15//   data-ekoo-locale="fr"                         — optional, "fr", "en", "auto", etc.
16//   data-ekoo-variant="WIDGET_CONFIG_REF"         — optional, reference of a widget configuration saved in the backoffice
17//   data-ekoo-review-id="REVIEW_ID"               — optional, target a specific review
18//   data-ekoo-on-event="callbackFnName"           — optional, window function name for event callback
19//
20// Appearance
21//   data-ekoo-direction="normal"                  — "normal" (default) or "reverse"
22//   data-ekoo-scale="1.2"                         — numeric scale factor
23//   data-ekoo-animation="pulse"                   — animation type (default: "pulse")
24//   data-ekoo-animation-duration="continuous"      — animation duration
25//   data-ekoo-always-open="true"                  — keep player always expanded
26//   data-ekoo-show-image="true"                   — show product image (default: true)
27//   data-ekoo-not-fully-clickable="true"          — restrict click zone to play button
28//   data-ekoo-autoplay="true"                     — auto-play audio on load
29//   data-ekoo-show-transcript="true"              — show transcript button
30//   data-ekoo-show-speed-button="true"            — show playback speed button
31//   data-ekoo-closed-state-main-text="..."        — main CTA text when closed
32//   data-ekoo-closed-state-secondary-text="..."   — secondary text when closed
33//
34// SPA & Shadow DOM
35//   data-ekoo-mode="spa"                          — "spa" or "static" (auto-detected by default)
36//   data-shadow-mode="closed"                     — "open" or "closed" (default: "open")
37//
38// Global JS config
39//   window.EKOO_FORCE_SPA = true                  — force SPA mode for all widgets
40//   window.ekooShadowMode = "open"                — global shadow DOM mode

⚠️

Définir avant le chargement du script

Définissez window.ekooOptions avant la balise de script Ekoo dans votre HTML. Le script lit cette configuration à l'initialisation — la définir après n'a aucun effet. Seules les propriétés websiteId et widgets sont supportées. Les autres options (direction, animation, etc.) se configurent via les attributs data HTML.

Référence de l'API

Fonction	Paramètres	Retour	Description
`ekooLoad`	aucun	void	Initialise tous les widgets sur la page
`ekooUnload`	aucun	void	Détruit toutes les instances de widget
`ekooReload`	aucun	void	Réinitialise tous les widgets (unload + load)

Ressources associées

Référence des attributs — Tous les attributs data pour l'élément widget
Référence des événements — Tous les événements émis par les widgets Ekoo