Intégration HTML / Vanilla JS

Intégration standard sans framework, directement en HTML

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

Méthode recommandée : data attributes

Ajoutez un conteneur avec les attributs data-ekoo-* et chargez le script officiel. Le widget s'initialise automatiquement.

Intégration simple
html
1<!-- Widget container -->
2<ekoo-widget
3  data-ekoo="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
4  data-ekoo-product-id="my-product-123"
5  data-ekoo-locale="fr"
6></ekoo-widget>
7
8<!-- Ekoo script — load once per page -->
9<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>

Product ID dynamique

Si l'identifiant du produit est dynamique (ex. extrait de l'URL ou d'un attribut de la page), vous pouvez utiliser une fonction JavaScript pour le récupérer et l'injecter dans l'attribut data-ekoo-product-id.

Product ID dynamique depuis l'URL
html
1<!-- Container — the ID will be injected by the script below -->
2<div id="ekoo-container"
3  data-ekoo="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
4  data-ekoo-locale="fr"
5></div>
6
7<script>
8  // Retrieve the product ID from the URL, e.g.: /products/my-product-123
9  function getProductId() {
10    const parts = window.location.pathname.split('/');
11    return parts[parts.length - 1];
12  }
13
14  const container = document.getElementById('ekoo-container');
15  if (container) {
16    container.setAttribute('data-ekoo-product-id', getProductId());
17  }
18</script>
19
20<!-- Ekoo script — AFTER the product ID injection -->
21<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>
✅

Déclarez les callbacks AVANT le script

Si vous utilisez data-ekoo-on-event pour recevoir les événements du widget, déclarez la fonction de callback avant le chargement du script Ekoo. Sinon, le script ne trouvera pas la fonction au moment de l'initialisation.

Callback d'événement
html
1<script>
2  // Declare the function BEFORE the Ekoo script
3  // The callback receives a single argument: the full stats body object
4  function onEkooEvent(data) {
5    console.log('Ekoo event:', data.stats.type, data);
6    // E.g.: send to Google Analytics, dataLayer, etc.
7  }
8</script>
9
10<ekoo-widget
11  data-ekoo="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
12  data-ekoo-on-event="onEkooEvent"
13  data-ekoo-product-id="my-product-123"
14  data-ekoo-locale="fr"
15></ekoo-widget>
16
17<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>

Pièges courants

  • Script chargé avant le conteneur : si le conteneur data-ekoo n'est pas encore dans le DOM, le widget ne se montera pas. Utilisez defer ou placez le script en fin de <body>.
  • Product ID manquant ou incorrect : le widget ne s'affichera pas si l'ID ne correspond à aucun audio publié.
  • Plusieurs scripts chargés : ne chargez le script widget-4.0.0-standalone.js qu'une seule fois par page, même si vous avez plusieurs conteneurs.
  • Callback non déclarée : la fonction référencée dans data-ekoo-on-event doit être accessible globalement (sur window).
  • Mauvaise URL du script : utilisez toujours widget-4.0.0-standalone.js, pas une ancienne version.

Aller plus loin

HTML / Vanilla JS — Documentation — Ekoo