FAQ

Questions fréquentes sur l'intégration du widget Ekoo

Quelle version du script utiliser ?

Utilisez toujours widget-4.0.0-standalone.js. C'est la version officielle et maintenue. L'URL complète est https://app.ekoo.co/widgets/widget-4.0.0-standalone.js.

Quelle différence entre les approches legacy et la version officielle ?

L'approche legacy utilise window.ekooOptions et d'anciennes versions du script (v3). L'approche officielle utilise des attributs data-ekoo-* directement sur le conteneur HTML. Si vous devez utiliser window.ekooOptions pour une création programmatique en v4, la structure attendue est { websiteId, widgets: [{ nodeId, productId, locale }] } — l'ancien format « à plat » n'est plus supporté. L'approche par attributs est plus simple, plus déclarative et recommandée pour toute nouvelle intégration. Consultez la page Legacy et migration.

Pourquoi mon widget ne s'affiche pas ?

Vérifiez ces points :

  • L'audio est bien publié dans le backoffice.
  • Le data-ekoo-product-id correspond à l'ID configuré dans le backoffice.
  • L'attribut data-ekoo="YOUR_WEBSITE_ID" est présent et correct sur le conteneur.
  • Le script widget-4.0.0-standalone.js est bien chargé (vérifiez l'onglet Network).
  • Aucune erreur JavaScript dans la console.
  • Le conteneur est présent dans le DOM avant le chargement du script.

Peut-on récupérer le product ID dynamiquement ?

Oui. Vous pouvez extraire l'ID depuis l'URL, un attribut du DOM ou une variable JavaScript, puis l'injecter dans l'attribut data-ekoo-product-id avant le chargement du script. Voir l'exemple dans le guide Vanilla JS.

Peut-on utiliser Ekoo dans une SPA ?

Oui. Utilisez l'API JavaScript : ekooLoad() au montage du composant, ekooUnload() au démontage, et ekooReload() si le product ID change sans démontage. Consultez les guides React, Svelte et Ionic.

Comment accélérer le chargement du widget ?

Chargez le script Ekoo dans le <head> avec l'attribut defer — le script se télécharge en parallèle du HTML, pour un meilleur LCP. Pour aller plus loin, ajoutez <link rel="preconnect" href="https://app.ekoo.co">. Voir la page Chargement du script.

Peut-on intégrer Ekoo avec Commanders Act (TagCommander) ?

Oui. Créez un tag Free input (custom) dans le container Commanders Act, qui injecte le conteneur <ekoo-widget> et charge le script. L'ID produit peut être lu dynamiquement depuis tc_vars.product_id. Pour les SPA, utilisez cact('trigger', 'product_view', {...}). Voir le guide Commanders Act.

Peut-on intégrer Ekoo avec GTM ?

Oui. Créez un tag Custom HTML dans GTM qui injecte le conteneur et le script. Consultez le guide Google Tag Manager pour un exemple complet.

Comment gérer plusieurs langues ?

Utilisez data-ekoo-locale="auto" pour une détection automatique basée sur le navigateur. Ou spécifiez une langue fixe : fr, en, etc.

Comment envoyer les événements à GA4 ?

Utilisez l'attribut data-ekoo-on-event pour référencer une fonction de callback globale, puis poussez les événements vers le dataLayer :

1function onEkooEvent(data) {
2  window.dataLayer = window.dataLayer || [];
3  window.dataLayer.push({
4    event: 'ekoo_' + data.stats.type.replace('-', '_'),
5    ekoo_event_type: data.stats.type,
6    ekoo_product_id: data.productRef
7  });
8}

Que faire si le produit change sans rechargement de page ?

Mettez à jour l'attribut data-ekoo-product-id du conteneur, puis appelez window.ekooReload(). Dans le cas du custom element <ekoo-widget>, utilisez setAttribute — le widget observe automatiquement les changements.

Quelle différence entre standalone et carousel ?

Standalone affiche un lecteur audio unique pour un produit. Carousel affiche une liste déroulante de plusieurs capsules audio. Le mode carousel n'est pas disponible dans widget-4.0.0-standalone.js — il nécessite widget-3.1.0.js. En v4 standalone, data-ekoo-type n'accepte que la valeur "standalone" (par défaut).

Ekoo utilise-t-il des cookies ?

Non. Le widget Ekoo n'utilise aucun cookie. Il n'y a aucune donnée personnelle collectée par le widget côté client.

Comment modifier l'apparence du widget ?

L'apparence du widget se gère depuis le backoffice — thème, textes CTA, animation, couleurs, position et CSS personnalisé y sont définis une fois, puis chargés automatiquement par le widget. Pour appliquer un autre habillage au même produit sur une page donnée, enregistrez une seconde configuration widget dans le backoffice et pointez dessus depuis votre HTML via data-ekoo-variant (par exemple homepage ou product-page) ; le produit, ses audios et ses reviewers ne changent pas. Pour des ajustements ponctuels, surchargez un réglage donné via les attributs d'apparence listés dans la référence.

FAQ — Documentation — Ekoo