Legacy and Migration

Migrating from an older version of the Ekoo widget

Context

Older integrations use patterns that are no longer recommended:

• Configuration via window.ekooOptions (global object with flat config format). In v4, ekooOptions is only used for programmatic widget creation and expects the structure { websiteId, widgets: [{ nodeId, productId, locale }] }.
• Old scripts: widget-3.x.x.js, widget-4.0.0.js (without the -standalone suffix).
• Widget injection via pure JavaScript (no data-ekoo attributes).

Recommended Approach

For any new integration, use:

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

What Changed Between v3 and v4

Migration Checklist

1. Replace the script: widget-3.x.x.js → widget-4.0.0-standalone.js.
2. Add data-ekoo="YOUR_WEBSITE_ID" to the <div> container.
3. Remove window.ekooOptions (old flat config format) and replace with data-ekoo-* attributes on the HTML container. If you need programmatic widget creation, use the new format: { websiteId, widgets: [{ nodeId, productId, locale }] }.
4. Add data-ekoo to the container (required marker attribute).
5. Test that the widget displays correctly with a published audio.
6. Check events: if you were using a callback in ekooOptions, migrate to data-ekoo-on-event.
7. Remove the old script — do not keep both versions side by side.

Before / After Example

1<!-- ❌ Old integration (v3.x) -->
2<script>
3  window.ekooOptions = {
4    websiteId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
5    productId: 'my-product-123',
6    locale: 'fr',
7    type: 'standalone'
8  };
9</script>
10<script src="https://app.ekoo.co/widgets/widget-3.x.x.js"></script>
11<div id="ekoo-widget"></div>

1<!-- ✅ New integration (v4.0.0-standalone) -->
2<ekoo-widget
3  data-ekoo="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
4  data-ekoo-product-id="my-product-123"
5  data-ekoo-locale="fr"
6></ekoo-widget>
7
8<script src="https://app.ekoo.co/widgets/widget-4.0.0-standalone.js"</script>

Resources

• Quickstart
• Integration Guides
• FAQ