Intégration

Choisissez la méthode d'intégration adaptée à votre stack technique

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

Deux approches

1. Data attributes Recommandé

L'approche standard : placez un conteneur avec des attributs data-ekoo-* et chargez le script officiel. C'est la méthode recommandée pour toutes les nouvelles intégrations.

Data attributes (recommandé)

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

Ancienne approche qui utilise un objet global window.ekooOptions pour configurer le widget de manière programmatique. La structure attendue contient un websiteId et un tableau widgets (chaque entrée référençant un conteneur DOM via nodeId). Elle est maintenue pour la rétro-compatibilité mais n'est plus recommandée pour les nouveaux projets.

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

Quelle que soit l'approche choisie, le script à charger est toujours widget-4.0.0-standalone.js.

Quand utiliser quelle approche ?

Nouvelle intégration → Data attributes. C'est plus simple, plus lisible et ne nécessite aucun JavaScript supplémentaire.
Migration d'une ancienne intégration → Passez aux data attributes dès que possible. Consultez le guide de migration.
Intégration SPA (React, Svelte, Ionic…) → Data attributes + API JavaScript (ekooLoad, ekooUnload, ekooReload) pour gérer le cycle de vie.

Guides par plateforme

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

💡

Performance — chargement du script

Quelle que soit votre stack, vous pouvez accélérer l'affichage du widget en chargeant le script Ekoo dans le <head> avec defer. Voir la page Chargement du script.