API client window.Moelleux

L'embed expose une API JavaScript sur window.Moelleux pour piloter le consentement depuis le code de votre site. L'API est gelée et versionnée (semver via Moelleux.version).

Garde-fou : attendre que l'API soit prête

L'embed se charge en asynchrone. N'appelez jamais window.Moelleux directement au chargement de la page : utilisez la file MoelleuxOnReady, qui fonctionne que votre code s'exécute avant ou après l'embed.

<script>
  window.MoelleuxOnReady = window.MoelleuxOnReady || [];
  window.MoelleuxOnReady.push(function (M) {
    // M === window.Moelleux, garanti prêt
    console.log(M.getConsent());
  });
</script>

Une fois l'embed chargé, vous pouvez aussi utiliser Moelleux.ready(cb).

Surface de l'API

Méthodes et propriétés disponibles sur window.Moelleux :

Méthode	Description
`version`	Version de l'embed (string).
`ready(cb)`	Appelle cb(Moelleux) dès que l'API est prête.
`getConsent()`	Retourne {choices, policyVersion, consentId, timestamp} ou null si aucun consentement.
`hasConsent(category)`	Retourne true/false pour une catégorie (analytics, marketing, functional, preferences, essential).
`acceptAll() / rejectAll()`	Tout accepter / tout refuser (les catégories requises restent actives).
`setConsent({...})`	Définit plusieurs catégories d'un coup (les clés inconnues sont ignorées).
`acceptCategory(cat) / denyCategory(cat)`	Accepte / refuse une seule catégorie.
`openPreferences()`	Ouvre la modale de préférences.
`reset()`	Efface le consentement enregistré.
`on(event, cb)`	Abonnement au bus d'événements ; retourne une fonction de désabonnement. Événements : consent.given, consent.changed, consent.reset, language.changed.
`getLanguage() / setLanguage('fr'\|'en')`	Lit / change la langue de l'UI (re-rend la bannière ; les deux locales sont déjà embarquées).
`getJurisdiction()`	Retourne la juridiction servie (ex. qc-loi25). Lecture seule (voir plus bas).
`showBadge() / hideBadge()`	Affiche / masque la pastille flottante de préférences (#mx-float).

La pastille flottante s'affiche automatiquement après consentement. Pour la désactiver entièrement, mettez banner_config.floatButton = false (vous déclenchez alors les préférences via votre propre lien + openPreferences()). showBadge() force l'affichage même si le flag est false.

Événement DOM (recommandé pour l'intégration)

À chaque consentement donné ou modifié, l'embed émet un CustomEvent sur document — écoutable sans dépendre de l'ordre de chargement.

document.addEventListener('moelleux:consent', function (e) {
  // e.detail = {choices, consentId, policyVersion, timestamp}
});

e.detail contient : {choices, consentId, policyVersion, timestamp}.

Classes CSS d'état (option cssClasses)

Quand l'option cssClasses est activée dans la configuration de la bannière, l'embed pose sur l'élément <html> les classes mx-consent-{cat} (catégorie accordée) et mx-consent-no-{cat} (refusée), plus mx-consent-ready. Les classes sont posées dès l'init (depuis le cookie) pour éviter tout flash de contenu.

.mx-consent-no-marketing .promo-marketing { display: none; }
.mx-consent-analytics    .badge-analytics  { display: inline; }

Exemple : masquer un bloc promo si le marketing est refusé, afficher un badge si l'analytique est accordée.

Juridiction : lecture seule

getJurisdiction() lit la juridiction servie, mais on ne change pas de juridiction au runtime : le script servi est spécifique à une juridiction (catégories, modèle de consentement et politique diffèrent). Pour une autre juridiction, chargez l'URL dédiée cdn.moelleux.ca/c/{site_key}-{juridiction}.js.

Recettes copier-coller

1. Activer une catégorie en JavaScript

Par exemple, sur un bouton « activer la vidéo » qui requiert la catégorie preferences.

Moelleux.acceptCategory('preferences');

2. Enregistrer l'état vers votre back-end

Écoutez l'événement et envoyez le détail à votre serveur. Le consentId sert de clé idempotente.

document.addEventListener('moelleux:consent', function (e) {
  fetch('/mon-backend/consentement', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(e.detail) // {choices, consentId, policyVersion, timestamp}
  });
});

3. Conditionner du code personnalisé au consentement

Initialisez votre code au chargement si le consentement existe déjà, et réagissez aux changements futurs.

Moelleux.ready(function (M) {
  if (M.hasConsent('analytics')) initMonAnalytics();
});
document.addEventListener('moelleux:consent', function (e) {
  if (e.detail.choices.analytics) initMonAnalytics();
});

4. Afficher / masquer par CSS

Avec l'option cssClasses activée, vous contrôlez l'affichage sans une seule ligne de JavaScript.

/* config bannière : cssClasses = true */
.mx-consent-no-analytics .analytics-widget { display: none; }
.mx-consent-marketing    .promo-banner     { display: block; }

Stabilité

L'API est additive et versionnée. Aucune méthode existante n'est retirée sans un bump de version majeure documenté.