Intégration Shopify

Ajoutez le widget Ekoo sur votre boutique Shopify avec Liquid

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

1. Ajouter le script dans theme.liquid

La méthode la plus simple consiste à charger le script Ekoo une seule fois dans votre fichier theme.liquid (ou layout/theme.liquid), juste avant la fermeture de </body>:

layout/theme.liquid

html

1  <!-- Widget Ekoo -->
2  <script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>
3</body>

2. Ajouter le conteneur sur la page produit

Dans votre template de page produit (sections/main-product.liquid ou templates/product.liquid), ajoutez le conteneur du widget en utilisant les variables Liquid :

Conteneur avec variables Liquid

liquid

1<ekoo-widget
2  data-ekoo="YOUR_WEBSITE_ID"
3  data-ekoo-product-id="{{ product.id }}"
4  data-ekoo-locale="fr"
5></ekoo-widget>

💡

product.id vs product.handle

Vous pouvez utiliser {{ product.id }} (identifiant numérique Shopify) ou {{ product.handle }} (slug URL) comme Product ID. Utilisez celui qui correspond à la configuration dans votre backoffice Ekoo.

3. Exemple complet

sections/main-product.liquid (extrait)

liquid

1{% comment %} Existing product page {% endcomment %}
2<div class="product-detail">
3  <h1>{{ product.title }}</h1>
4  <p>{{ product.description }}</p>
5
6  {% comment %} Widget Ekoo {% endcomment %}
7  <ekoo-widget
8    data-ekoo="YOUR_WEBSITE_ID"
9    data-ekoo-product-id="{{ product.id }}"
10    data-ekoo-locale="{{ request.locale.iso_code }}"
11  ></ekoo-widget>
12
13  <button type="submit" name="add" class="btn">
14    Add to cart
15  </button>
16</div>

La variable {{ request.locale.iso_code }} permet d'adapter automatiquement la langue du widget à celle de la boutique (utile pour les boutiques multilingues).

4. Variante carousel

⚠️

Attention

La variante carousel n'est pas disponible dans widget-4.0.0-standalone.js. Elle nécessite widget-3.1.0.js.

Carousel Shopify (widget-3.1.0.js uniquement)

liquid

1<!-- ⚠️ Carousel requires widget-3.1.0.js — NOT available in 4.0.0-standalone -->
2<ekoo-widget
3  data-ekoo="YOUR_WEBSITE_ID"
4  data-ekoo-product-id="{{ product.id }}"
5  data-ekoo-type="carousel"
6  data-ekoo-locale="{{ request.locale.iso_code }}"
7></ekoo-widget>

5. Compatibilité Dawn / OS 2.0

Les thèmes Shopify OS 2.0 (comme Dawn) utilisent des sections et des blocs. Deux options :

Via le Theme Editor : ajoutez un bloc Custom Liquid dans la section produit et collez le code du conteneur data-ekoo.
Via le code : éditez directement le fichier sections/main-product.liquid comme décrit ci-dessus.

✅

Theme Editor recommandé

Pour les thèmes OS 2.0, préférez l'ajout via le Theme Editor. Cela évite de modifier le code du thème et facilite les mises à jour futures du thème.

Bloc Custom Liquid dans le Theme Editor

liquid

1{% comment %}
2  Paste this code into a "Custom Liquid" block
3  via the Shopify Theme Editor.
4{% endcomment %}
5<ekoo-widget
6  data-ekoo="YOUR_WEBSITE_ID"
7  data-ekoo-product-id="{{ product.id }}"
8  data-ekoo-locale="{{ request.locale.iso_code }}"
9></ekoo-widget>

Intégration Shopify

1. Ajouter le script dans theme.liquid

2. Ajouter le conteneur sur la page produit

3. Exemple complet

4. Variante carousel

5. Compatibilité Dawn / OS 2.0

Aller plus loin