Widget Standalone

Le widget standalone affiche un seul audio sous forme d'icône avec une barre d'information qui se déplie et se replie au clic. C'est le format le plus courant pour présenter un avis audio sur une fiche produit.

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

Comportement

Au chargement, le widget affiche une icône compacte avec un texte d'appel à l'action.
Au clic, la barre d'information se déplie pour révéler le lecteur audio et les détails de l'avis.
Un second clic replie la barre (sauf si alwaysOpen est activé).
Le widget ne s'affiche que si un audio publié est associé au produit.

Intégration minimale

Ajoutez le script Ekoo et un conteneur avec les attributs data-ekoo et data-ekoo-product-id :

Intégration minimale

html

1<!-- Ekoo Script -->
2<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>
3
4<!-- Widget container -->
5<ekoo-widget
6  data-ekoo="YOUR_WEBSITE_ID"
7  data-ekoo-product-id="YOUR_PRODUCT_ID"
8></ekoo-widget>

ℹ️

Pré-requis

Le widget ne s'affiche que si un audio publié est associé au produit dans le backoffice Ekoo. Vérifiez que l'audio est bien publié avant de tester votre intégration.

Paramètres spécifiques au standalone

Paramètre	Type	Défaut	Description
`reviewId`	string	—	Identifiant d'un avis spécifique à afficher. Si omis, le widget affiche le premier audio publié du produit.
`direction`	`normal` \| `reverse`	`normal`	Sens de déploiement de la barre. normal = sens standard (gauche vers droite), reverse = sens inversé (droite vers gauche).
`animation`	string	`pulse`	Type d'animation. Par défaut, un effet de pulsation (anneaux) attire l'attention sur le widget.
`animationDuration`	string	`continuous`	Durée de l'animation. Par défaut, continue (boucle indéfiniment).
`iconListen`	string (URL)	—	URL d'une icône personnalisée pour le bouton d'écoute.
`chevron`	boolean	true	Affiche ou masque le chevron indicateur d'ouverture/fermeture.
`closedStateMainText`	string	—	Texte principal affiché lorsque le widget est replié.
`closedStateSecondaryText`	string	—	Texte secondaire affiché sous le texte principal à l'état fermé.
`closedStateDisplayChevron`	boolean	true	Affiche ou masque le chevron à l'état fermé.
`alwaysOpen`	boolean	false	Si activé, le widget reste toujours déplié et ne peut pas être replié par l'utilisateur.

Direction du widget

Le paramètre direction contrôle le sens de déploiement de la barre d'information :

normal (par défaut) — Sens de déploiement standard (gauche vers droite en LTR).
reverse — Sens inversé. Utile pour les mises en page alignées à droite.

Animation

Le widget utilise une animation pulse par défaut — des anneaux pulsants qui attirent l'attention sur le lecteur audio. L'animation tourne en continu jusqu'à ce que l'utilisateur interagisse avec le widget.

Paramètre	Défaut	Description
`animation`	`pulse`	Type d'animation. L'effet pulse par défaut crée des anneaux pulsants autour de l'icône du widget.
`animationDuration`	`continuous`	Durée de l'animation. Par défaut, continue (boucle indéfiniment).

Exemple complet

Widget standalone personnalisé

html

1<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>
2
3<ekoo-widget
4  data-ekoo="YOUR_WEBSITE_ID"
5  data-ekoo-product-id="YOUR_PRODUCT_ID"
6  data-ekoo-locale="fr"
7  data-ekoo-direction="reverse"
8  data-ekoo-animation="pulse"
9  data-ekoo-always-open="true"
10  data-ekoo-closed-state-main-text="Listen to a customer review"
11  data-ekoo-closed-state-secondary-text="Verified audio"
12  data-ekoo-scale="1.2"
13  data-ekoo-on-event="onEkooEvent"
14></ekoo-widget>

💡

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 comme data-ekoo-closed-state-main-text ou data-ekoo-scale ne sont nécessaires que si vous souhaitez surcharger la configuration du backoffice pour une instance spécifique du widget.

💡

Optimiser le chargement

Pour un démarrage plus rapide du widget, chargez le script dans le <head> avec defer. Voir Chargement du script pour le pattern complet (preconnect, preload, par stack).

Même produit, plusieurs configurations widget

Un même produit peut être affiché avec plusieurs habillages de widget à différents endroits de votre site, sans le dupliquer. Enregistrez chaque habillage comme une configuration widget dans le backoffice, attribuez-lui une référence stable (par exemple homepage ou product-page), puis pointez dessus depuis votre HTML avec data-ekoo-variant :

Même produit, deux configurations widget

html

1<!-- Same product (same audios, same reviewers), two different widget skins. -->
2<!-- "homepage" and "product-page" are example values; replace them with the references -->
3<!-- of widget configurations saved in your backoffice. -->
4
5<!-- Homepage block -->
6<ekoo-widget
7  data-ekoo="YOUR_WEBSITE_ID"
8  data-ekoo-product-id="SKU-001"
9  data-ekoo-variant="homepage"
10></ekoo-widget>
11
12<!-- Product page block -->
13<ekoo-widget
14  data-ekoo="YOUR_WEBSITE_ID"
15  data-ekoo-product-id="SKU-001"
16  data-ekoo-variant="product-page"
17></ekoo-widget>

Les deux blocs affichent le même produit, avec les mêmes audios et les mêmes reviewers — seul l'habillage du widget change.

ℹ️

Si aucune configuration ne correspond

Ekoo cherche d'abord une configuration dont la référence correspond à la valeur de l'attribut. À défaut, il essaie un match legacy par nom de configuration (pour les anciennes intégrations), puis la configuration attachée au produit, et enfin la configuration par défaut de votre site. Les références sont uniques au sein d'un site et d'un type de widget, ce qui garantit qu'une seule configuration est sélectionnée.

ℹ️

Syntaxe élément personnalisé

Vous pouvez aussi utiliser <ekoo-widget> au lieu d'un <div> :

<ekoo-widget data-ekoo="..." data-ekoo-product-id="..."></ekoo-widget>

Les deux syntaxes sont équivalentes. Le script Ekoo détecte automatiquement les deux.