FAQ

Frequently asked questions about Ekoo widget integration

Which script version should I use?

Always use widget-4.0.0-standalone.js. This is the official and maintained version. The full URL is https://app.ekoo.co/widgets/widget-4.0.0-standalone.js.

What is the difference between the legacy approach and the official version?

The legacy approach uses window.ekooOptions and older script versions (v3). The official approach uses data-ekoo-* attributes directly on the HTML container. If you need to use window.ekooOptions for programmatic widget creation in v4, the expected structure is { websiteId, widgets: [{ nodeId, productId, locale }] } — the old flat config format is no longer supported. The attribute-based approach is simpler, more declarative, and recommended for all new integrations. See the Legacy and Migration page.

Why is my widget not showing?

Check the following:

  • The audio is published in the backoffice.
  • The data-ekoo-product-id matches the ID configured in the backoffice.
  • The data-ekoo="YOUR_WEBSITE_ID" attribute is present and correct on the container.
  • The widget-4.0.0-standalone.js script is loaded (check the Network tab).
  • No JavaScript errors in the console.
  • The container is present in the DOM before the script loads.

Can I retrieve the product ID dynamically?

Yes. You can extract the ID from the URL, a DOM attribute, or a JavaScript variable, then inject it into the data-ekoo-product-id attribute before the script loads. See the example in the Vanilla JS guide.

Can I use Ekoo in a SPA?

Yes. Use the JavaScript API: ekooLoad() on component mount, ekooUnload() on unmount, and ekooReload() if the product ID changes without unmounting. See the React, Svelte and Ionic guides.

How can I make the widget load faster?

Load the Ekoo script in the <head> with the defer attribute — the script downloads in parallel with the HTML, which improves LCP. For an extra boost, add <link rel="preconnect" href="https://app.ekoo.co">. See the Script loading page.

Can I integrate Ekoo with Commanders Act (TagCommander)?

Yes. Create a Free input (custom) tag in your Commanders Act container that injects the <ekoo-widget> container and loads the script. The product ID can be read dynamically from tc_vars.product_id. For SPAs, use cact('trigger', 'product_view', {...}). See the Commanders Act guide.

Can I integrate Ekoo with GTM?

Yes. Create a Custom HTML tag in GTM that injects the container and script. See the Google Tag Manager guide for a complete example.

How do I handle multiple languages?

Use data-ekoo-locale="auto" for automatic detection based on the browser. Or specify a fixed language: fr, en, etc.

How do I send events to GA4?

Use the data-ekoo-on-event attribute to reference a global callback function, then push the events to the 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}

What if the product changes without a page reload?

Update the data-ekoo-product-id attribute on the container, then call window.ekooReload(). When using the custom element <ekoo-widget>, use setAttribute — the widget automatically observes changes.

What is the difference between standalone and carousel?

Standalone displays a single audio player for a product. Carousel displays a scrollable list of multiple audio clips. Carousel mode is not available in widget-4.0.0-standalone.js — it requires widget-3.1.0.js. In v4 standalone, data-ekoo-type only accepts "standalone" (the default).

Does Ekoo use cookies?

No. The Ekoo widget does not use any cookies. No personal data is collected by the widget on the client side.

How do I change the widget appearance?

Manage the widget's appearance from the backoffice — theme, CTA texts, animation, colors, position and custom CSS are all set there, then loaded automatically by the widget. To apply a different styling to the same product on a given page, save a second widget configuration in the backoffice and reference it from your HTML with data-ekoo-variant (for example homepage or product-page); the product, its audios and its reviewers stay the same. For one-off tweaks, override individual settings via the appearance attributes listed in the reference.

FAQ — Documentation — Ekoo