JavaScript API

1window.ekooLoad(): void

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

1window.ekooUnload(): void

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

1window.ekooReload(): void

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();

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};

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    audioPreload?: "metadata" | "none";    // Standalone 4.0.0 only; "none" disables autoplay
9  }>;
10}
11
12// HTML data attributes (on each widget container):
13// Core
14//   data-ekoo="WEBSITE_ID"                       — required, your website UUID
15//   data-ekoo-product-id="PRODUCT_ID"             — required, product identifier
16//   data-ekoo-locale="fr"                         — optional, "fr", "en", "auto", etc.
17//   data-ekoo-variant="WIDGET_CONFIG_REF"         — optional, reference of a widget configuration saved in the backoffice
18//   data-ekoo-review-id="REVIEW_ID"               — optional, target a specific review
19//   data-ekoo-on-event="callbackFnName"           — optional, window function name for event callback
20//
21// Appearance
22//   data-ekoo-direction="normal"                  — "normal" (default) or "reverse"
23//   data-ekoo-scale="1.2"                         — numeric scale factor
24//   data-ekoo-animation="pulse"                   — animation type (default: "pulse")
25//   data-ekoo-animation-duration="continuous"      — animation duration
26//   data-ekoo-always-open="true"                  — keep player always expanded
27//   data-ekoo-show-image="true"                   — show product image (default: true)
28//   data-ekoo-not-fully-clickable="true"          — restrict click zone to play button
29//   data-ekoo-autoplay="true"                     — auto-play audio on load
30//   data-ekoo-audio-preload="none"                — standalone 4.0.0 only; load on first play (disables autoplay)
31//   data-ekoo-show-transcript="true"              — show transcript button
32//   data-ekoo-show-speed-button="true"            — show playback speed button
33//   data-ekoo-closed-state-main-text="..."        — main CTA text when closed
34//   data-ekoo-closed-state-secondary-text="..."   — secondary text when closed
35//
36// SPA & Shadow DOM
37//   data-ekoo-mode="spa"                          — "spa" or "static" (auto-detected by default)
38//   data-shadow-mode="closed"                     — "open" or "closed" (default: "open")
39//
40// Global JS config
41//   window.EKOO_FORCE_SPA = true                  — force SPA mode for all widgets
42//   window.ekooShadowMode = "open"                — global shadow DOM mode