Legacy et migration

Migrer depuis une ancienne version du widget Ekoo

Contexte

Des intégrations plus anciennes utilisent des patterns qui ne sont plus recommandés :

• Configuration via window.ekooOptions (objet global avec format « à plat »). En v4, ekooOptions n'est utilisé que pour la création programmatique et attend la structure { websiteId, widgets: [{ nodeId, productId, locale }] }.
• Scripts anciens : widget-3.x.x.js, widget-4.0.0.js (sans le suffixe -standalone).
• Injection du widget via JavaScript pur (pas d'attributs data-ekoo).

Approche recommandée

Pour toute nouvelle intégration, utilisez :

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>

Ce qui a changé entre v3 et v4

Checklist de migration

1. Remplacez le script : widget-3.x.x.js → widget-4.0.0-standalone.js.
2. Ajoutez data-ekoo="YOUR_WEBSITE_ID" sur le conteneur <div>.
3. Supprimez window.ekooOptions (ancien format à plat) et remplacez par des attributs data-ekoo-* sur le conteneur HTML. Si vous avez besoin d'une création programmatique, utilisez le nouveau format : { websiteId, widgets: [{ nodeId, productId, locale }] }.
4. Ajoutez data-ekoo sur le conteneur (attribut marqueur obligatoire).
5. Testez que le widget s'affiche correctement avec un audio publié.
6. Vérifiez les événements : si vous utilisiez un callback dans ekooOptions, migrez vers data-ekoo-on-event.
7. Supprimez l'ancien script — ne conservez pas les deux versions côte à côte.

Exemple avant / après

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>

Ressources

• Quickstart
• Guides d'intégration
• FAQ