Intégration Commanders Act

Injectez le widget Ekoo via un tag personnalisé dans TagCommander

Commanders Act (anciennement TagCommander) est une plateforme européenne de gestion de tags. Comme Google Tag Manager, elle permet d'ajouter le widget Ekoo sur vos pages produit sans modifier le code source du site. Vous créez un tag Free input (custom) qui insère le conteneur et charge le script Ekoo.

Le widget charge automatiquement sa configuration depuis le backoffice. Les attributs d'apparence sont des surcharges optionnelles — inutile de les définir si le backoffice est configuré.
Attributs principaux
data-ekooReq
string
UUID du site Ekoo. Visible dans le backoffice → Paramètres du site.
data-ekoo-product-idReq
string
Référence produit (doit correspondre exactement au catalogue Ekoo).
data-ekoo-locale
string·default: auto
Code langue : fr, en, es, it, de, ar, cn, tw, hk, jp, kr, nl, tr, pl, pt, lu, be, ru. "auto" = détection navigator.language.
data-ekoo-variant
string
Référence stable d’une configuration widget. Le produit, ses audios et ses reviewers restent pilotés par data-ekoo-product-id ; seul l’habillage change.
data-ekoo-review-id
string
ID d'un avis audio spécifique. Si omis, le premier avis publié est utilisé.
data-ekoo-on-event
string (fn name)
Nom d'une fonction globale window appelée à chaque événement widget (printed, played-0, played-25…).
Apparence — surcharges backoffice
data-ekoo-direction
normal | reverse·default: normal
Sens d'expansion. normal = gauche→droite, reverse = droite→gauche.
data-ekoo-scale
number·default: 1
Facteur de zoom (ex: "1.2" pour 20% plus grand).
data-ekoo-animation
string·default: pulse
Type d'animation de l'icône au repos.
data-ekoo-animation-duration
string·default: continuous
Durée de l'animation.
data-ekoo-always-open
boolean·default: false
Si "true", le widget reste toujours déplié.
data-ekoo-show-image
boolean·default: true
Afficher ou masquer l'image produit dans le widget.
data-ekoo-not-fully-clickable
boolean·default: false
Si "true", seul le bouton lecture est cliquable.
data-ekoo-autoplay
boolean·default: false
Lecture audio automatique au chargement.
data-ekoo-show-transcript
boolean·default: false
Afficher un bouton pour lire la transcription.
data-ekoo-show-speed-button
boolean·default: false
Afficher un contrôle de vitesse de lecture.
data-ekoo-closed-state-main-text
string
Texte CTA principal affiché quand le widget est replié.
data-ekoo-closed-state-secondary-text
string
Texte secondaire sous le CTA quand le widget est replié.
SPA & Shadow DOM
data-ekoo-mode
spa | static·default: auto
Force le mode rendu. Auto-détecté (Next.js, Nuxt, React, Vue, Angular, Sapper). À utiliser seulement si la détection auto échoue.
data-shadow-mode
open | closed·default: open
"open" (par défaut) permet l'inspection, l'accès CSS externe et le tracking analytics. Définir à "closed" pour isoler complètement le widget.
Config JS globale
window.EKOO_FORCE_SPA = true
Force le mode SPA globalement (alternative à data-ekoo-mode="spa" sur chaque widget).
window.ekooShadowMode = "open"
Shadow DOM mode global (alternative à data-shadow-mode sur chaque widget).

1. Créer un tag personnalisé

  1. Ouvrez votre container TagCommander.
  2. Allez à l'étape EDIT et cliquez sur Add a tag.
  3. Choisissez le type Free input (custom) dans la bibliothèque de tags.
  4. Dans la section JAVASCRIPT CODE, collez le code ci-dessous (remplace le contenu par défaut).
  5. Décochez Use Tag Cleaner si vous voulez préserver le code tel quel.
Tag personnalisé — Commanders Act
html
1<script>
2(function() {
3  // 1. Create the widget container
4  var container = document.createElement('div');
5  container.setAttribute('data-ekoo', 'YOUR_WEBSITE_ID');
6  container.setAttribute('data-ekoo-product-id', 'MY_PRODUCT_ID');
7  container.setAttribute('data-ekoo-locale', 'fr');
8
9  // 2. Insert the container at the desired location
10  //    Adjust the CSS selector to match your site
11  var target = document.querySelector('.product-detail');
12  if (target) {
13    target.appendChild(container);
14  } else {
15    document.body.appendChild(container);
16  }
17
18  // 3. Load the Ekoo script (only once per page)
19  if (!document.querySelector('script[src*="widget-4.0.0-standalone"]')) {
20    var script = document.createElement('script');
21    script.src = 'https://app.ekoo.co/widgets/widget-4.0.0-standalone.js';
22    script.defer = true;
23    document.head.appendChild(script);
24  } else if (window.ekooLoad) {
25    window.ekooLoad();
26  }
27})();
28</script>

2. Cibler le bon élément sur la page

Utilisez document.querySelector() pour positionner le widget à l'endroit voulu. Sélecteurs courants :

  • .product-detail — bloc principal de la fiche produit
  • #add-to-cart — juste avant/après le bouton d'ajout au panier
  • [data-product-id] — élément portant l'ID produit
💡

Astuce

Inspectez votre page produit dans le navigateur, identifiez le sélecteur CSS idéal, puis testez-le dans la console avec document.querySelector('...').

3. Product ID dynamique via tc_vars

Commanders Act expose vos données métier via l'objet global window.tc_vars (le dataLayer Commanders Act). Sur une page produit, vous y trouverez typiquement tc_vars.product_id ou tc_vars.product_array.

Product ID dynamique depuis tc_vars
html
1<script>
2(function() {
3  // Read the product ID from the Commanders Act dataLayer (tc_vars)
4  // Common conventions: tc_vars.product_id or tc_vars.product_array[0].id
5  var tcVars = window.tc_vars || {};
6  var productId =
7    tcVars.product_id ||
8    (Array.isArray(tcVars.product_array) && tcVars.product_array[0]
9      ? tcVars.product_array[0].id
10      : null);
11
12  if (!productId) return; // Not a product page → do nothing
13
14  var container = document.createElement('div');
15  container.setAttribute('data-ekoo', 'YOUR_WEBSITE_ID');
16  container.setAttribute('data-ekoo-product-id', productId);
17  container.setAttribute('data-ekoo-locale', tcVars.env_language || 'fr');
18
19  var target = document.querySelector('.product-detail');
20  if (target) target.appendChild(container);
21
22  if (!document.querySelector('script[src*="widget-4.0.0-standalone"]')) {
23    var script = document.createElement('script');
24    script.src = 'https://app.ekoo.co/widgets/widget-4.0.0-standalone.js';
25    script.defer = true;
26    document.head.appendChild(script);
27  } else if (window.ekooLoad) {
28    window.ekooLoad();
29  }
30})();
31</script>
✅

Préparez tc_vars avant le container

L'objet tc_vars doit être renseigné avant le chargement du fichier container. Sinon, le tag se déclenche avec un product_id vide et le widget ne se montera pas.

4. Configurer le déclencheur

Le tag doit se déclencher uniquement sur les pages produit, après que le DOM soit prêt. Trois stratégies courantes dans Commanders Act :

  • Page View + condition — déclencheur page_view filtré par tc_vars.page_type === 'product'.
  • URL contains — filtre sur l'URL de la page (ex. /product/).
  • Événement custom — déclenchez via cact('trigger', 'product_view', {...}) (particulièrement utile pour les SPA, voir section 5).

5. Sites SPA — déclenchement par événement

Sur une SPA (React, Vue, Angular…), la navigation ne recharge pas la page : un déclencheur Page View ne se déclenche qu'une seule fois. Utilisez plutôt l'API événementielle de Commanders Act :

Déclenchement via cact() — SPA
html
1<script>
2// Listen to a custom Commanders Act event fired by your site
3// (e.g. cact('trigger', 'product_view', { product_id: '...' }))
4window.cact = window.cact || function () {
5  (window.cact.q = window.cact.q || []).push(arguments);
6};
7
8cact('on', 'product_view', function (data) {
9  if (!data || !data.product_id) return;
10
11  var container = document.createElement('div');
12  container.setAttribute('data-ekoo', 'YOUR_WEBSITE_ID');
13  container.setAttribute('data-ekoo-product-id', data.product_id);
14  container.setAttribute('data-ekoo-locale', data.locale || 'fr');
15
16  var target = document.querySelector('.product-detail') || document.body;
17  target.appendChild(container);
18
19  if (!document.querySelector('script[src*="widget-4.0.0-standalone"]')) {
20    var script = document.createElement('script');
21    script.src = 'https://app.ekoo.co/widgets/widget-4.0.0-standalone.js';
22    script.defer = true;
23    document.head.appendChild(script);
24  } else if (window.ekooReload) {
25    window.ekooReload();
26  }
27});
28</script>

Côté application, votre code SPA doit émettre l'événement à chaque navigation produit :

1// À chaque navigation vers une page produit
2cact('trigger', 'product_view', {
3  product_id: 'my-product-123',
4  locale: 'fr',
5});

6. Élément cible non encore présent

⚠️

Le tag s'exécute avant le rendu

Si votre site rend le bloc produit côté client (lazy-loading, hydratation différée), l'élément cible peut ne pas exister au moment où le tag s'exécute. Dans ce cas, utilisez un MutationObserver pour attendre son apparition.

MutationObserver — attente de l'élément cible
html
1<script>
2(function() {
3  function injectEkoo(target) {
4    var container = document.createElement('div');
5    container.setAttribute('data-ekoo', 'YOUR_WEBSITE_ID');
6    container.setAttribute('data-ekoo-product-id',
7      (window.tc_vars && window.tc_vars.product_id) || 'MY_PRODUCT_ID');
8    container.setAttribute('data-ekoo-locale', 'fr');
9    target.appendChild(container);
10
11    if (!document.querySelector('script[src*="widget-4.0.0-standalone"]')) {
12      var script = document.createElement('script');
13      script.src = 'https://app.ekoo.co/widgets/widget-4.0.0-standalone.js';
14      script.defer = true;
15      document.head.appendChild(script);
16    } else if (window.ekooLoad) {
17      window.ekooLoad();
18    }
19  }
20
21  var target = document.querySelector('.product-detail');
22  if (target) {
23    injectEkoo(target);
24    return;
25  }
26
27  var observer = new MutationObserver(function(mutations, obs) {
28    var el = document.querySelector('.product-detail');
29    if (el) {
30      obs.disconnect();
31      injectEkoo(el);
32    }
33  });
34  observer.observe(document.body, { childList: true, subtree: true });
35})();
36</script>

7. Prévisualiser et publier

  1. Activez le mode Debug de Commanders Act (paramètre URL ?tc_debug=1 ou via l'extension navigateur).
  2. Naviguez vers une page produit ayant un audio publié.
  3. Vérifiez dans la console Commanders Act que le tag se déclenche, et que le widget Ekoo s'affiche.
  4. Si tout est bon, déployez le container en production.

Consentement (TrustCommander)

Le widget Ekoo n'utilise aucun cookie et ne collecte aucune donnée personnelle côté client. Il n'a donc pas besoin de consentement RGPD pour fonctionner. Vous pouvez le déclencher dès la page chargée, sans attendre l'acceptation de la CMP.

ℹ️

Si votre policy interne l'exige

Si vous préférez tout de même conditionner le chargement à un consentement (ex. catégorie « Expérience utilisateur » ou « Personnalisation »), utilisez l'événement consent.update de Commanders Act :

Déclenchement après consentement
javascript
1cact('on', 'consent.update', function (consent) {
2  // Adaptez 'experience' à la catégorie de consentement de votre CMP
3  if (consent && consent.experience === true) {
4    // Charge le tag Ekoo (insertion conteneur + script)
5    cact('trigger', 'product_view', {
6      product_id: window.tc_vars && window.tc_vars.product_id,
7    });
8  }
9});

Performance — charger le script plus tôt

Pour réduire le temps avant l'affichage du widget, vous pouvez créer un second tag (déclencheur All Pages) qui injecte simplement le script Ekoo dans le <head>. Voir la page Chargement du script pour le pattern complet.

Pièges courants

  • tc_vars vide — le tag se déclenche avant que le dataLayer ne soit renseigné. Forcez l'ordre via le déclencheur page_view (qui attend tc_vars) plutôt que DOM Ready.
  • Tag déclenché sur toutes les pages — pensez au filtre tc_vars.page_type === 'product' ou un filtre URL pour éviter de charger le widget partout.
  • Script chargé en double — la garde querySelector('script[src*="widget-4.0.0-standalone"]') évite d'ajouter le script plusieurs fois.
  • SPA sans événement custom — un tag page_view classique ne se redéclenche pas. Utilisez cact('trigger', 'product_view', …) depuis votre code SPA à chaque navigation.
  • Politique CSP — si votre site utilise une CSP stricte, ajoutez app.ekoo.co à la directive script-src.
  • Tag Cleaner activé — peut altérer les IIFE et la logique conditionnelle. Décochez l'option si le code semble réécrit différemment.
ℹ️

Note

Besoin d'aide ? Consultez la FAQ ou contactez le support Ekoo.

Commanders Act — Documentation — Ekoo