Intégration HTML / Vanilla JS
Intégration standard sans framework, directement en HTML
data-ekooReqdata-ekoo-product-idReqdata-ekoo-localeautodata-ekoo-variantdata-ekoo-review-iddata-ekoo-on-eventdata-ekoo-directionnormaldata-ekoo-scale1data-ekoo-animationpulsedata-ekoo-animation-durationcontinuousdata-ekoo-always-openfalsedata-ekoo-show-imagetruedata-ekoo-not-fully-clickablefalsedata-ekoo-autoplayfalsedata-ekoo-audio-preloadmetadatadata-ekoo-show-transcriptfalsedata-ekoo-show-speed-buttonfalsedata-ekoo-closed-state-main-textdata-ekoo-closed-state-secondary-textdata-ekoo-modeautodata-shadow-modeopenwindow.EKOO_FORCE_SPA = truewindow.ekooShadowMode = "open"Méthode recommandée : data attributes
Ajoutez un conteneur avec les attributs data-ekoo-* et chargez le script officiel. Le widget s'initialise automatiquement.
1<!-- Widget container -->2<ekoo-widget3 data-ekoo="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"4 data-ekoo-product-id="my-product-123"5 data-ekoo-locale="fr"6></ekoo-widget>78<!-- 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.
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>67<script>8 // Retrieve the product ID from the URL, e.g.: /products/my-product-1239 function getProductId() {10 const parts = window.location.pathname.split('/');11 return parts[parts.length - 1];12 }1314 const container = document.getElementById('ekoo-container');15 if (container) {16 container.setAttribute('data-ekoo-product-id', getProductId());17 }18</script>1920<!-- 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.
1<script>2 // Declare the function BEFORE the Ekoo script3 // The callback receives a single argument: the full stats body object4 function onEkooEvent(data) {5 console.log('Ekoo event:', data.stats.type, data);6 // E.g.: send to Google Analytics, dataLayer, etc.7 }8</script>910<ekoo-widget11 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>1617<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>Cycle de vie du widget
Le widget émet ekoovisible lorsqu'un avis est sélectionné et prêt à être affiché, et ekoohidden lorsqu'il ne peut pas s'afficher. Les écouteurs doivent être déclarés avant le script du widget.
1<script>2 // Register listeners BEFORE loading the Ekoo widget script.3 document.addEventListener('ekoovisible', (event) => {4 const { productId, reviewId, review } = event.detail;5 console.log('Selected audio:', { productId, reviewId, review });6 });78 document.addEventListener('ekoohidden', ({ detail }) => {9 console.warn('Widget hidden:', detail.reason);10 });11</script>ekoovisible contient les identifiants du widget, du produit et de l'avis, ainsi qu'un objet review public (audio et contributeur). Ce contrat est versionné et ses champs pourront être enrichis sans casser les intégrations. ekoohidden expose l'une des raisons suivantes : noMatchingProduct, noAudios, experimentDisabled ou loadError.
Pièges courants
- Script chargé avant le conteneur : si le conteneur
data-ekoon'est pas encore dans le DOM, le widget ne se montera pas. Utilisezdeferou 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.jsqu'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-eventdoit être accessible globalement (surwindow). - Mauvaise URL du script : utilisez toujours
widget-4.0.0-standalone.js, pas une ancienne version.