Widget Lifecycle

The Ekoo widget exposes three JavaScript methods to control its lifecycle: ekooLoad, ekooUnload and ekooReload. These methods are essential for single-page applications (SPA) and dynamic integrations.

window.ekooLoad()

Initializes the widget and scans the DOM for Ekoo containers. This method is called automatically on page load. You only need to call it manually in the following cases:

• Your application is a SPA (React, Vue, Angular, Svelte…) and the container is added dynamically to the DOM.
• You inject the widget after the initial page load (e.g., via a third-party script or GTM).

1// Initialize all widgets on the page
2window.ekooLoad();

window.ekooUnload()

Removes all Ekoo widgets from the DOM and frees associated resources (event listeners, audio players, network connections). Essential to prevent memory leaks in SPAs.

1// Remove all widgets (call before leaving the page/component)
2window.ekooUnload();

window.ekooReload()

Forces a complete widget reload. Equivalent to an ekooUnload() followed by an ekooLoad(). New in v4, this method is particularly useful for dynamic product changes.

1// When the displayed product changes dynamically
2document.querySelector('[data-ekoo-product-id]')
3  .setAttribute('data-ekoo-product-id', 'new-product-456');
4
5// Unload then re-initialize
6window.ekooReload();

Display Conditions

The widget only displays when all of the following conditions are met:

• The Ekoo script is loaded and executed.
• A container with the data-ekoo attribute (or an <ekoo-widget> element) is present in the DOM.
• The websiteId is valid.
• A productId is defined and matches an existing product in the backoffice.
• At least one published audio is associated with the product.
• The requested locale matches an available locale (if specified).

Configuration Resolution

The widget automatically fetches configuration from the Ekoo backoffice based on the websiteId and productId. Local data-* attributes defined in the HTML take precedence over the remote backoffice configuration.

Complete SPA Pattern

Here is the recommended pattern for integrating the Ekoo widget in a single-page application:

1// 1. On product page mount
2function onProductPageMount(productId) {
3  // Make sure no residual widget exists
4  window.ekooUnload();
5
6  // Update the product ID in the DOM
7  const container = document.querySelector('[data-ekoo]');
8  if (container) {
9    container.setAttribute('data-ekoo-product-id', productId);
10  }
11
12  // Load the widget
13  window.ekooLoad();
14}
15
16// 2. On product change (without unmounting)
17function onProductChange(newProductId) {
18  const container = document.querySelector('[data-ekoo]');
19  if (container) {
20    container.setAttribute('data-ekoo-product-id', newProductId);
21  }
22  window.ekooReload();
23}
24
25// 3. On component unmount
26function onProductPageUnmount() {
27  window.ekooUnload();
28}