Shopify Integration

Add the Ekoo widget to your Shopify store with Liquid

The widget auto-loads its config from the backoffice. Appearance attributes are optional overrides — no need to set them if the backoffice is configured.

Core attributes

data-ekooReq

string

Your Ekoo website UUID. Found in the backoffice → Site settings.

data-ekoo-product-idReq

string

Product reference (must match exactly what is in your Ekoo catalog).

data-ekoo-locale

string·default: auto

Locale code: fr, en, es, it, de, ar, cn, tw, hk, jp, kr, nl, tr, pl, pt, lu, be, ru. "auto" = navigator.language detection.

data-ekoo-variant

string

Stable reference of a widget configuration. The product, its audios, and its reviewers still come from data-ekoo-product-id; only the widget styling changes.

data-ekoo-review-id

string

ID of a specific audio review. If omitted, the first published review is used.

data-ekoo-on-event

string (fn name)

Name of a global window function called on each widget event (printed, played-0, played-25…).

Appearance — backoffice overrides

data-ekoo-direction

normal | reverse·default: normal

Expansion direction. normal = left-to-right, reverse = right-to-left.

data-ekoo-scale

number·default: 1

Scale factor (e.g. "1.2" for 20% larger).

data-ekoo-animation

string·default: pulse

Animation type for the widget icon at rest.

data-ekoo-animation-duration

string·default: continuous

Animation duration.

data-ekoo-always-open

boolean·default: false

If "true", the widget stays permanently expanded.

data-ekoo-show-image

boolean·default: true

Show or hide the product image in the widget.

data-ekoo-not-fully-clickable

boolean·default: false

If "true", only the play button is clickable.

data-ekoo-autoplay

boolean·default: false

Automatically start audio playback on load.

data-ekoo-show-transcript

boolean·default: false

Show a button to read the audio transcript.

data-ekoo-show-speed-button

boolean·default: false

Show a playback speed control.

data-ekoo-closed-state-main-text

string

Main CTA text shown when the widget is collapsed.

data-ekoo-closed-state-secondary-text

string

Secondary text below the CTA when the widget is collapsed.

SPA & Shadow DOM

data-ekoo-mode

spa | static·default: auto

Forces rendering mode. Auto-detected (Next.js, Nuxt, React, Vue, Angular, Sapper). Only use if auto-detection fails.

data-shadow-mode

open | closed·default: open

"open" (default) enables inspection, external CSS access and analytics tracking. Set to "closed" to fully isolate the widget.

Global JS config

window.EKOO_FORCE_SPA = true

Forces SPA mode globally (alternative to data-ekoo-mode="spa" on each widget).

window.ekooShadowMode = "open"

Global Shadow DOM mode (alternative to data-shadow-mode on each widget).

1. Add the script to theme.liquid

The simplest method is to load the Ekoo script once in your theme.liquid (or layout/theme.liquid), just before the closing </body>tag:

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. Add the container to the product page

In your product page template (sections/main-product.liquid or templates/product.liquid), add the widget container using Liquid variables:

Container with Liquid variables

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

You can use {{ product.id }} (Shopify numeric identifier) or {{ product.handle }} (URL slug) as the Product ID. Use whichever matches the configuration in your Ekoo backoffice.

3. Full example

sections/main-product.liquid (excerpt)

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>

The {{ request.locale.iso_code }} variable automatically adapts the widget language to the store's language (useful for multilingual stores).

4. Carousel variant

⚠️

Warning

The carousel variant is not available in widget-4.0.0-standalone.js. It requires widget-3.1.0.js.

Shopify Carousel (widget-3.1.0.js only)

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. Dawn / OS 2.0 Compatibility

Shopify OS 2.0 themes (such as Dawn) use sections and blocks. Two options:

Via the Theme Editor: add a Custom Liquid block in the product section and paste the data-ekoo container code.
Via code: directly edit the sections/main-product.liquid file as described above.

✅

Theme Editor recommended

For OS 2.0 themes, prefer adding via the Theme Editor. This avoids modifying the theme code and makes future theme updates easier.

Custom Liquid block in the 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>

Shopify Integration

1. Add the script to theme.liquid

2. Add the container to the product page

3. Full example

4. Carousel variant

5. Dawn / OS 2.0 Compatibility

Going further