Integration

Choose the integration method that best fits your tech stack

The widget auto-loads its config from the backoffice. Appearance attributes are optional overrides — no need to set them if the backoffice is configured.
Core attributes
data-ekooReq
string
Your Ekoo website UUID. Found in the backoffice → Site settings.
data-ekoo-product-idReq
string
Product reference (must match exactly what is in your Ekoo catalog).
data-ekoo-locale
string·default: auto
Locale code: fr, en, es, it, de, ar, cn, tw, hk, jp, kr, nl, tr, pl, pt, lu, be, ru. "auto" = navigator.language detection.
data-ekoo-variant
string
Stable reference of a widget configuration. The product, its audios, and its reviewers still come from data-ekoo-product-id; only the widget styling changes.
data-ekoo-review-id
string
ID of a specific audio review. If omitted, the first published review is used.
data-ekoo-on-event
string (fn name)
Name of a global window function called on each widget event (printed, played-0, played-25…).
Appearance — backoffice overrides
data-ekoo-direction
normal | reverse·default: normal
Expansion direction. normal = left-to-right, reverse = right-to-left.
data-ekoo-scale
number·default: 1
Scale factor (e.g. "1.2" for 20% larger).
data-ekoo-animation
string·default: pulse
Animation type for the widget icon at rest.
data-ekoo-animation-duration
string·default: continuous
Animation duration.
data-ekoo-always-open
boolean·default: false
If "true", the widget stays permanently expanded.
data-ekoo-show-image
boolean·default: true
Show or hide the product image in the widget.
data-ekoo-not-fully-clickable
boolean·default: false
If "true", only the play button is clickable.
data-ekoo-autoplay
boolean·default: false
Automatically start audio playback on load.
data-ekoo-show-transcript
boolean·default: false
Show a button to read the audio transcript.
data-ekoo-show-speed-button
boolean·default: false
Show a playback speed control.
data-ekoo-closed-state-main-text
string
Main CTA text shown when the widget is collapsed.
data-ekoo-closed-state-secondary-text
string
Secondary text below the CTA when the widget is collapsed.
SPA & Shadow DOM
data-ekoo-mode
spa | static·default: auto
Forces rendering mode. Auto-detected (Next.js, Nuxt, React, Vue, Angular, Sapper). Only use if auto-detection fails.
data-shadow-mode
open | closed·default: open
"open" (default) enables inspection, external CSS access and analytics tracking. Set to "closed" to fully isolate the widget.
Global JS config
window.EKOO_FORCE_SPA = true
Forces SPA mode globally (alternative to data-ekoo-mode="spa" on each widget).
window.ekooShadowMode = "open"
Global Shadow DOM mode (alternative to data-shadow-mode on each widget).

Two Approaches

1. Data Attributes Recommended

The standard approach: place a container with data-ekoo-* attributes and load the official script. This is the recommended method for all new integrations.

Data attributes (recommended)
html
1<ekoo-widget
2  data-ekoo="MY_WEBSITE_ID"
3  data-ekoo-product-id="MY_PRODUCT_ID"
4  data-ekoo-locale="fr"
5></ekoo-widget>
6
7<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>

2. window.ekooOptions Legacy

The older approach that uses a global window.ekooOptions object to configure the widget programmatically. The expected structure contains a websiteId and a widgets array (each entry referencing a DOM container via nodeId). It is maintained for backward compatibility but is no longer recommended for new projects.

window.ekooOptions (legacy)
javascript
1window.ekooOptions = {
2  websiteId: "YOUR_WEBSITE_ID",
3  widgets: [
4    {
5      nodeId: "my-container",       // ID of the target DOM element
6      productId: "my-product-123",
7      locale: "fr"                  // optional
8    }
9  ]
10};
ℹ️

Note

Regardless of the approach you choose, the script to load is always widget-4.0.0-standalone.js.

When to Use Which Approach?

  • New integration → Data attributes. It is simpler, more readable, and requires no additional JavaScript.
  • Migrating from an old integration → Switch to data attributes as soon as possible. See the migration guide.
  • SPA integration (React, Svelte, Ionic…) → Data attributes + JavaScript API (ekooLoad, ekooUnload, ekooReload) to manage the lifecycle.

Platform Guides

HTML / Vanilla JS →Google Tag Manager →Commanders Act →React →Svelte / SvelteKit →Ionic / Capacitor →WordPress →Shopify →
💡

Performance — script loading

Whatever your stack, you can speed up the widget's appearance by loading the Ekoo script in the <head> with defer. See the Script loading page.

Overview — Documentation — Ekoo