Quickstart

Intégrez le widget Ekoo sur votre site en quelques minutes

Le widget charge automatiquement sa configuration depuis le backoffice. Les attributs d'apparence sont des surcharges optionnelles — inutile de les définir si le backoffice est configuré.

Attributs principaux

data-ekooReq

string

UUID du site Ekoo. Visible dans le backoffice → Paramètres du site.

data-ekoo-product-idReq

string

Référence produit (doit correspondre exactement au catalogue Ekoo).

data-ekoo-locale

string·default: auto

Code langue : fr, en, es, it, de, ar, cn, tw, hk, jp, kr, nl, tr, pl, pt, lu, be, ru. "auto" = détection navigator.language.

data-ekoo-variant

string

Référence stable d’une configuration widget. Le produit, ses audios et ses reviewers restent pilotés par data-ekoo-product-id ; seul l’habillage change.

data-ekoo-review-id

string

ID d'un avis audio spécifique. Si omis, le premier avis publié est utilisé.

data-ekoo-on-event

string (fn name)

Nom d'une fonction globale window appelée à chaque événement widget (printed, played-0, played-25…).

Apparence — surcharges backoffice

data-ekoo-direction

normal | reverse·default: normal

Sens d'expansion. normal = gauche→droite, reverse = droite→gauche.

data-ekoo-scale

number·default: 1

Facteur de zoom (ex: "1.2" pour 20% plus grand).

data-ekoo-animation

string·default: pulse

Type d'animation de l'icône au repos.

data-ekoo-animation-duration

string·default: continuous

Durée de l'animation.

data-ekoo-always-open

boolean·default: false

Si "true", le widget reste toujours déplié.

data-ekoo-show-image

boolean·default: true

Afficher ou masquer l'image produit dans le widget.

data-ekoo-not-fully-clickable

boolean·default: false

Si "true", seul le bouton lecture est cliquable.

data-ekoo-autoplay

boolean·default: false

Lecture audio automatique au chargement.

data-ekoo-show-transcript

boolean·default: false

Afficher un bouton pour lire la transcription.

data-ekoo-show-speed-button

boolean·default: false

Afficher un contrôle de vitesse de lecture.

data-ekoo-closed-state-main-text

string

Texte CTA principal affiché quand le widget est replié.

data-ekoo-closed-state-secondary-text

string

Texte secondaire sous le CTA quand le widget est replié.

SPA & Shadow DOM

data-ekoo-mode

spa | static·default: auto

Force le mode rendu. Auto-détecté (Next.js, Nuxt, React, Vue, Angular, Sapper). À utiliser seulement si la détection auto échoue.

data-shadow-mode

open | closed·default: open

"open" (par défaut) permet l'inspection, l'accès CSS externe et le tracking analytics. Définir à "closed" pour isoler complètement le widget.

Config JS globale

window.EKOO_FORCE_SPA = true

Force le mode SPA globalement (alternative à data-ekoo-mode="spa" sur chaque widget).

window.ekooShadowMode = "open"

Shadow DOM mode global (alternative à data-shadow-mode sur chaque widget).

1. Code minimal

Ajoutez ces deux éléments sur votre page : un conteneur avec les attributs data-ekoo et le script officiel.

Intégration standalone

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>

⚠️

Audio publié obligatoire

Le widget ne s'affiche que si au moins un audio est publié pour le product-id indiqué. Vérifiez le statut dans le backoffice Ekoo.

2. Détail des attributs

Attributs du conteneur

Attribut	Requis	Description
`data-ekoo`	Obligatoire	Marque l'élément comme conteneur du widget Ekoo.
`data-ekoo-product-id`	Obligatoire	Identifiant du produit. Doit correspondre à l'ID configuré dans le backoffice.
`data-ekoo-locale`	Optionnel	Langue du widget (`fr`, `en`, `auto`…). Par défaut, détection automatique.
`data-ekoo-type`	Optionnel	Type de widget : `standalone` (défaut). Peut être omis.
`data-ekoo-variant`	Optionnel	Référence d'une configuration widget enregistrée dans le backoffice (ex : "homepage"). Sélectionne l'habillage appliqué ; le produit et ses audios restent pilotés par data-ekoo-product-id.
`data-ekoo-on-event`	Optionnel	Nom d'une fonction globale appelée lors des événements du widget (played-0, played-25, etc.).

Attributs du script

Attribut	Requis	Description
`src`	Obligatoire	Toujours `https://app.ekoo.co/widgets/widget-4.0.0-standalone.js`
`defer`	Recommandé	Charge le script sans bloquer le rendu de la page.

💡

Sites multilingues

Utilisez data-ekoo-locale="auto" pour que le widget s'adapte automatiquement à la langue du navigateur de vos visiteurs.

3. Exemple complet

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. Configuration JavaScript

Vous pouvez aussi configurer les widgets via window.ekooOptions au lieu d'utiliser les attributs HTML. C'est utile pour les applications SPA ou lorsque vous devez gérer plusieurs widgets dynamiquement.

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>

Si le widget ne s'affiche pas

Vérifiez que l'audio est bien publié dans le backoffice.
Vérifiez que le data-ekoo-product-id correspond à l'identifiant du produit dans le backoffice.
Vérifiez que le data-ekoo est correct (UUID du site).
Assurez-vous que le script widget-4.0.0-standalone.js est bien chargé (onglet Network des DevTools).
Vérifiez qu'il n'y a pas d'erreur JavaScript dans la console.
Si vous utilisez un bloqueur de publicités, désactivez-le temporairement.
Assurez-vous que le conteneur data-ekoo est présent dans le DOM au moment du chargement du script.

ℹ️

Note

Si le problème persiste, contactez le support Ekoo en précisant votre Website ID et le Product ID concerné.

5. Élément personnalisé alternatif

Au lieu d'un <div>, vous pouvez utiliser l'élément personnalisé <ekoo-widget> directement. Les deux syntaxes sont équivalentes — le script Ekoo détecte automatiquement les deux.

Syntaxe élément personnalisé

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. Options avancées

Attributs avancés

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 l'isolation complète du Shadow DOM (par défaut : open, ce qui autorise l'inspection DevTools et le tracking analytics).
data-ekoo-mode="spa" — Force le mode SPA si l'auto-détection échoue (rare).
Le mode SPA est auto-détecté pour Next.js, Nuxt, React, Vue, Angular et Sapper.

ℹ️

Configuration distante

Le widget Ekoo récupère automatiquement sa configuration visuelle complète depuis le backoffice Ekoo en se basant sur votre websiteId et productId. Cela inclut : le thème, les couleurs, les textes CTA, les paramètres d'animation, la position, et le CSS personnalisé. Vous n'avez pas besoin de définir des attributs d'apparence dans votre HTML — la configuration du backoffice est appliquée automatiquement. Les attributs data ne sont nécessaires que pour surcharger la configuration du backoffice pour une instance spécifique du widget.

Prochaines étapes

Guides d'intégration par plateforme (React, Svelte, Shopify, GTM…)
Gérer votre contenu audio
FAQ