Quickstart

Add the Ekoo widget to your site in just a few minutes

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).

1. Minimal Code

Add these two elements to your page: a container with the data-ekoo attributes and the official script.

Standalone integration

html

1<!-- Widget container -->
2<ekoo-widget
3  data-ekoo="YOUR_WEBSITE_ID"
4  data-ekoo-product-id="YOUR_PRODUCT_ID"
5  data-ekoo-locale="fr"
6></ekoo-widget>
7
8<!-- Ekoo script (load once) -->
9<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>

⚠️

Published audio required

The widget only appears if at least one audio is published for the product-id specified. Check the status in the Ekoo backoffice.

2. Attribute Details

Container Attributes

Attribute	Required	Description
`data-ekoo`	Required	Marks the element as an Ekoo widget container.
`data-ekoo-product-id`	Required	Product identifier. Must match the ID configured in the backoffice.
`data-ekoo-locale`	Optional	Widget language (`fr`, `en`, `auto`…). Defaults to automatic detection.
`data-ekoo-type`	Optional	Widget type: `standalone` (default). Can be omitted.
`data-ekoo-variant`	Optional	Reference of a widget configuration saved in the backoffice (e.g. "homepage"). Picks the styling to apply; product and audios still come from data-ekoo-product-id.
`data-ekoo-on-event`	Optional	Name of a global function called on widget events (played-0, played-25, etc.).

Script Attributes

Attribute	Required	Description
`src`	Required	Always `https://app.ekoo.co/widgets/widget-4.0.0-standalone.js`
`defer`	Recommended	Loads the script without blocking page rendering.

💡

Multilingual sites

Use data-ekoo-locale="auto" to let the widget automatically adapt to your visitors' browser language.

3. Complete Example

page-produit.html

html

1<!DOCTYPE html>
2<html lang="fr">
3<head>
4  <meta charset="UTF-8" />
5  <title>Mon produit</title>
6</head>
7<body>
8
9  <h1>Mon super produit</h1>
10
11  <!-- Ekoo Widget -->
12  <ekoo-widget
13    data-ekoo="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
14    data-ekoo-product-id="my-product-123"
15    data-ekoo-locale="fr"
16  ></ekoo-widget>
17
18  <!-- Ekoo Script -->
19  <script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>
20
21</body>
22</html>

4. JavaScript Configuration

You can also configure widgets via window.ekooOptions instead of HTML attributes. This is useful for SPA applications or when you need to manage multiple widgets dynamically.

Configuration via ekooOptions

html

1<!-- Target container -->
2<div id="ekoo-container"></div>
3
4<script>
5  window.ekooOptions = {
6    websiteId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
7    widgets: [
8      {
9        nodeId: "ekoo-container",
10        productId: "my-product-123",
11        locale: "fr"
12      }
13    ]
14  };
15</script>
16
17<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>

If the Widget Does Not Appear

Verify that the audio is published in the backoffice.
Verify that the data-ekoo-product-id matches the product identifier in the backoffice.
Verify that the data-ekoo is correct (site UUID).
Make sure the widget-4.0.0-standalone.js script is loaded (check the Network tab in DevTools).
Check for JavaScript errors in the console.
If you are using an ad blocker, temporarily disable it.
Make sure the data-ekoo container is present in the DOM when the script loads.

ℹ️

Note

If the issue persists, contact Ekoo support with your Website ID and the affected Product ID.

5. Custom Element Alternative

Instead of a <div>, you can use the <ekoo-widget> custom element directly. Both syntaxes are equivalent — the Ekoo script detects both automatically.

Custom element syntax

html

1<!-- Alternative: use the custom element directly -->
2<ekoo-widget
3  data-ekoo="YOUR_WEBSITE_ID"
4  data-ekoo-product-id="YOUR_PRODUCT_ID"
5  data-ekoo-locale="fr"
6></ekoo-widget>

6. Advanced Options

Advanced attributes

html

1<!-- Shadow DOM: opt into full style isolation (default: open) -->
2<ekoo-widget
3  data-ekoo="YOUR_WEBSITE_ID"
4  data-ekoo-product-id="YOUR_PRODUCT_ID"
5  data-shadow-mode="closed"
6></ekoo-widget>
7
8<!-- Force SPA mode if auto-detection fails (rare) -->
9<ekoo-widget
10  data-ekoo="YOUR_WEBSITE_ID"
11  data-ekoo-product-id="YOUR_PRODUCT_ID"
12  data-ekoo-mode="spa"
13></ekoo-widget>

data-shadow-mode="closed" — Force full Shadow DOM isolation (default: open, which allows DevTools inspection and analytics tracking).
data-ekoo-mode="spa" — Forces SPA mode if auto-detection fails (rare).
SPA mode is auto-detected for Next.js, Nuxt, React, Vue, Angular, and Sapper.

ℹ️

Remote configuration

The Ekoo widget automatically fetches its full visual configuration from the Ekoo backoffice based on your websiteId and productId. This includes: theme, colors, CTA texts, animation settings, position, and custom CSS. You don't need to set appearance attributes in your HTML — the backoffice configuration is applied automatically. Data attributes are only needed to override the backoffice configuration for a specific widget instance.

Next Steps

Platform Integration Guides (React, Svelte, Shopify, GTM…)
Managing Your Audio Content
FAQ