Référence des attributs

Référence complète de tous les attributs data supportés par l'élément widget Ekoo.

Attributs principaux

Attributs d'apparence

SPA & Shadow DOM

Configuration JavaScript globale

Ces variables globales affectent tous les widgets de la page. Définissez-les avant de charger le script Ekoo.

1<script>
2  // Force SPA mode for all widgets on the page
3  window.EKOO_FORCE_SPA = true;
4
5  // Set Shadow DOM mode globally (default: "open")
6  window.ekooShadowMode = "closed";
7</script>
8
9<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>

Descriptions détaillées

data-ekoo

Votre identifiant unique de site web (websiteId), disponible dans le backoffice Ekoo sous les paramètres de votre site. Cette valeur doit correspondre exactement — elle est utilisée pour récupérer votre configuration de widget, styling, et contenu audio associé. Se place sur le conteneur du widget (div ou ekoo-widget), pas sur la balise script.

data-ekoo-product-id

Relie le widget à un produit spécifique dans votre catalogue Ekoo. La valeur doit correspondre exactement à ce qui est configuré dans le backoffice Ekoo. Cet attribut est sensible à la casse — assurez-vous qu'il correspond précisément à votre référence produit.

data-ekoo-locale

Filtre le contenu audio par langue en utilisant un code locale Ekoo (ex : "fr", "en"). Si omis, Ekoo utilise la détection de langue du navigateur pour déterminer le contenu le plus approprié. Quand aucune locale correspondante n'est trouvée, le widget revient à afficher tous les audios disponibles.

data-ekoo-variant

Sélectionne la configuration widget à appliquer via sa référence. Chaque configuration widget du backoffice possède une référence stable que vous choisissez vous-même (par exemple homepage ou product-page) ; renseignez cette valeur ici pour charger la configuration correspondante.

Le produit, ses audios et ses reviewers sont toujours résolus via data-ekoo-product-id. Cet attribut ne change que le widget lui-même — son thème, ses textes CTA, l'animation, la position, le CSS personnalisé. Vous pouvez ainsi réutiliser le même produit à différents endroits de votre site avec des habillages différents, sans le dupliquer.

Au chargement du widget, Ekoo cherche la configuration dans cet ordre, dans le périmètre de votre site et du type de widget courant :

1. La configuration dont la référence correspond à la valeur de l'attribut.
2. Pour les anciennes intégrations, une configuration dont le nom correspond à la valeur.
3. La configuration attachée au produit.
4. 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 : la même référence peut être réutilisée sur des types différents (par exemple standalone et carrousel) sans collision. Si l'attribut est omis, la recherche démarre directement à l'étape 3.

data-ekoo-mode

Force le mode de rendu du widget. Le widget auto-détecte les frameworks SPA (Next.js, Nuxt, React, Vue, Angular, Sapper) et passe automatiquement en mode SPA. Définissez ceci à "spa" seulement si l'auto-détection échoue, ou "static" pour forcer le rendu statique.

data-shadow-mode

Contrôle l'encapsulation Shadow DOM pour le widget. La valeur par défaut "open" permet l'accès CSS externe aux éléments internes du widget, l'inspection via les DevTools et le tracking analytics. Définissez à "closed" si vous avez besoin d'une isolation complète des styles, empêchant vos styles de page d'affecter le widget et vice versa.

Exemples d'utilisation

Via les attributs HTML

1<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>
2
3<ekoo-widget
4  data-ekoo="abc123"
5  data-ekoo-product-id="SKU-001"
6  data-ekoo-locale="fr"
7  data-ekoo-on-event="onEkooEvent"
8></ekoo-widget>

Via window.ekooOptions

1<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>
2
3<script>
4  window.ekooOptions = {
5    websiteId: "abc123",
6    widgets: [
7      {
8        nodeId: "ekoo-container",     // string (element ID) or function returning an HTMLElement
9        productId: "SKU-001",          // string or function returning a string
10        locale: "fr"                   // string or function returning a string (optional)
11      }
12    ]
13  };
14</script>
15
16<div id="ekoo-container"></div>

Via l'élément personnalisé

L'élément <ekoo-widget> est une alternative au <div> avec data-ekoo attributs :

1<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>
2
3<ekoo-widget
4  data-ekoo="abc123"
5  data-ekoo-product-id="SKU-001"
6  data-ekoo-locale="fr"
7></ekoo-widget>

Ressources associées

• API JavaScript — Fonctions de contrôle programmatique du widget
• Référence des événements — Tous les événements émis par les widgets Ekoo