Aller au contenu

API JavaScript et événements

← Développeurs

Ce que vous pouvez faire ici

  • Ne lancer vos propres scripts qu’une fois que le visiteur accepte leur catégorie.
  • Lire ou modifier le choix du visiteur, et ouvrir les choix depuis votre propre bouton.
  • Faire attendre le consentement aux balises de Google Tag Manager, avec deux événements de la couche de données.

Tout ce qui figure sur cette page est fourni par Cookie Rocks Pro, sur les pages où son bandeau est activé. L’Audit gratuit de Cookie Rocks n’ajoute aucun script aux pages de vos visiteurs : il n’a donc aucune API JavaScript et ne déclenche aucun événement.

QuoiNomExtension
APIwindow.CookieRocksPro
Événements du DOM, sur documentcookie-rocks:ready, cookie-rocks:change, cookie-rocks:ui, cookie-rocks:panel, cookie-rocks:reload, wp_consent_type_definedPro
Événements de Google Tag Manager, dans dataLayercr_consent_ready, cr_consent_updatePro
Attributs HTMLdata-cr-category, data-cr-service, data-cr-type, data-cr-src, data-cr-allow, data-cr-open, data-cr-ignorePro

D’autres variables globales que vous pouvez voir dans la page (crHead, crConfig, crData, crUi, crPanel, crEmbeds, crPurge, crPreviewLocale) sont internes et peuvent changer. Ne les utilisez pas.

Quand l’API est prête

Le script du bandeau se charge avec defer. Il crée window.CookieRocks, applique le choix enregistré et déclenche cookie-rocks:ready, avant DOMContentLoaded. Un script qui s’exécute plus tôt, comme un script en ligne dans la page, ne voit pas encore window.CookieRocks. Cette fonction utilitaire fonctionne dans les deux cas :

function whenCookieRocks(callback) {
	if (window.CookieRocks) {
		callback();
	} else {
		document.addEventListener('cookie-rocks:ready', callback, { once: true });
	}
}

whenCookieRocks(function () {
	CookieRocks.onConsent('statistics', function () {
		// Start your own statistics tool here.
	});
});

Il n’y a pas de window.CookieRocks quand le bandeau est désactivé, ni sur les pages ouvertes dans un constructeur de pages.

window.CookieRocks

MéthodeCe qu’il fait
CookieRocks.open()Ouvre le panneau des détails, en chargeant d’abord son code si besoin.
CookieRocks.acceptAll()Enregistre « Tout accepter ». Le marketing reste refusé quand le site respecte Global Privacy Control et que le navigateur l’envoie, ou quand le compte connecté l’a refusé. Sur un site pour enfants, le marketing et les statistiques restent refusés.
CookieRocks.rejectAll()Enregistre « Tout refuser » : chaque catégorie facultative est refusée, et les outils autorisés un par un sont retirés aussi.
CookieRocks.allowService(id)Autorise un seul outil du catalogue, par exemple 'youtube'.
CookieRocks.hasChoice()true une fois que le visiteur a répondu au bandeau.
CookieRocks.hasConsent(category, service)true si la catégorie est acceptée. Voir ci-dessous.
CookieRocks.getConsent()L’état de chaque catégorie : {necessary, preferences, statistics, marketing, audience}, en booléens.
CookieRocks.getServices()Les identifiants des outils autorisés un par un.
CookieRocks.setProfile(profile)Définit les règles qui s’appliquent au visiteur, avec Règles par pays. Cookie Rocks l’appelle lui-même dès qu’il connaît le pays du visiteur : laissez-le faire, sauf si vous localisez les visiteurs avec votre propre code. profile.p vaut strict ou objection. Quand aucune règle n’arrive dans les 3 secondes, les règles strictes s’appliquent.
CookieRocks.onChange(callback)Appelle callback(consent, services) après chaque choix.
CookieRocks.onConsent(category, callback)Appelle callback tout de suite si la catégorie est déjà acceptée, sinon une seule fois, quand elle est acceptée.

Dans hasConsent et onConsent, category vaut necessary, preferences, statistics, marketing ou audience. Les alias analytics (statistiques), ads et advertising (marketing) et functional (nécessaires, donc toujours acceptée) fonctionnent aussi. Une liste séparée par des virgules, comme 'statistics,marketing', signifie que l’une suffit. Avec l’identifiant service facultatif, hasConsent retourne aussi true quand cet outil a été autorisé seul.

if (CookieRocks.hasConsent('marketing', 'youtube')) {
	// The visitor accepted marketing, or allowed YouTube on its own.
}

document.querySelector('.my-settings-link').addEventListener('click', function (event) {
	event.preventDefault();
	CookieRocks.open();
});

Quand un choix retire un consentement donné auparavant, Cookie Rocks supprime les cookies et le stockage du navigateur correspondants, puis recharge la page : un script déjà en cours ne peut pas être arrêté. Autoriser un outil qui doit être présent au chargement de la page, comme un captcha, recharge aussi la page, et garde ce que le visiteur a saisi dans les formulaires.

Événements du DOM

Ces événements sont envoyés sur document.

ÉvénementQuandevent.detail
cookie-rocks:readyÀ chaque chargement de page, une fois le choix enregistré appliqué.{consent, services, given}
cookie-rocks:changeAprès chaque choix : bandeau, panneau des détails, API, le bouton d’une vidéo ou d’une carte, ou un élément data-cr-allow. Avec Règles par pays, aussi avant tout choix, quand les règles du pays du visiteur changent les catégories activées.{consent, services, given}
cookie-rocks:uiQuand le code du bandeau a été chargé : à la première visite, ou quand le visiteur rouvre les choix.Aucun
cookie-rocks:panelQuand le code du panneau des détails a été chargé. Il ne se charge qu’en cas de besoin : quand le pointeur ou le clavier s’approche du bouton « Je choisis », ou quand les choix sont rouverts.Aucun
cookie-rocks:reloadJuste avant que la page se recharge pour charger un outil autorisé seul qui doit être présent au chargement de la page, comme reCAPTCHA. Cookie Rocks s’en sert pour garder ce que le visiteur a saisi dans les formulaires.{consent, services, given}
wp_consent_type_definedÀ chaque chargement de page et après chaque choix, une fois le choix transmis à WP Consent API quand cette extension est active (une convention de WP Consent API). Cookie Rocks définit aussi window.wp_consent_type à optin, ou à optout quand le bandeau ne fait qu’informer.Aucun

Dans detail, consent est l’objet retourné par getConsent(), services est le tableau des outils autorisés un par un, et given indique si le visiteur a répondu au bandeau.

document.addEventListener('cookie-rocks:change', function (event) {
	if (event.detail.consent.marketing) {
		// Marketing is accepted.
	}
});

Événements de Google Tag Manager

Ces événements sont ajoutés à dataLayer.

ÉvénementQuandVariables
cr_consent_readySur chaque page, depuis le script de l’en-tête de la page, avant les balises Google.cr_consent (l’état de chaque catégorie, en booléens), cr_consent_status (given ou pending)
cr_consent_updateAprès chaque changement de choix, refus compris, et seulement à ce moment-là. Aussi quand un outil est autorisé seul. Avec Règles par pays, aussi avant tout choix, quand les règles du pays du visiteur changent les catégories actives.cr_consent, cr_services (outils autorisés un par un), cr_consent_status

Dans Google Tag Manager, utilisez un déclencheur Événement personnalisé sur cr_consent_ready et sur cr_consent_update, avec la condition : Variable de couche de données cr_consent.marketing (ou cr_consent.statistics) égale à true. L’événement seul ne suffit pas : cr_consent_update part aussi après « Tout refuser », et ne repart pas sur les pages suivantes. Ou, à la place, exigez dans les paramètres d’autorisation de la balise ad_storage (publicité) ou analytics_storage (statistiques). Voir Google Consent Mode, Tag Manager et Site Kit.

// What Cookie Rocks pushes after a choice:
{
	event: 'cr_consent_update',
	cr_consent: { necessary: true, preferences: false, statistics: true, marketing: false, audience: false },
	cr_services: [],
	cr_consent_status: 'given'
}

Retenir vos propres scripts et cadres

Les cookies connus sont retenus d’eux-mêmes. Pour un autre script, donnez-lui le type text/plain et une catégorie. Cookie Rocks l’exécute dès que le visiteur accepte cette catégorie :

<script type="text/plain" src="https://example.com/tool.js"></script>
<script type="text/plain">/* inline code */</script>
<script type="text/plain" src="https://example.com/module.js"></script>
<iframe></iframe>
AttributActifEffet
data-cr-category<script type="text/plain">, <iframe>La catégorie qui libère l’élément. Mêmes noms et alias que hasConsent ; une liste séparée par des virgules signifie que l’une suffit. L’attribut data-category est lu aussi.
data-cr-serviceIdemUn identifiant d’outil du catalogue : l’élément s’exécute aussi quand cet outil seul est autorisé.
data-cr-type<script>Le type que le script reçoit quand il s’exécute, comme module.
data-cr-src<iframe>L’adresse que le cadre charge une fois autorisé. Sans src, le cadre reste vide jusque-là.
data-cr-ignore<script>, <link rel="stylesheet">Le blocage automatique laisse ce script ou cette feuille de style tranquille, même s’il correspond à un outil connu. Utilisez-le seulement pour du code qui ne dépose aucun cookie et n’envoie aucune donnée personnelle, ou que la loi laisse se charger sans consentement. Il ne s’applique pas aux iframes.
data-cr-allowTout élémentUn clic autorise l’outil nommé dans l’attribut, par exemple data-cr-allow="youtube".
data-cr-openTout élémentUn clic ouvre le panneau des détails. La valeur sale ouvre plutôt la vue « Do Not Sell or Share », sur les sites qui s’adressent aux États-Unis. Un lien vers #cr-preferences et un élément avec la classe cr-open-preferences fonctionnent aussi. Voir Codes courts.

Une fois le consentement donné, les scripts retenus se téléchargent ensemble, puis s’exécutent dans l’ordre de la page. Un script externe est attendu avant que le suivant s’exécute, 3 secondes au plus : un code qui appelle un outil juste après son script doit attendre que cet outil soit prêt (son propre rappel, ou l’événement de chargement de son script). Les scripts dont le type ne s’exécute jamais, comme application/ld+json, ne sont jamais touchés. Quand un script retenu appartient à une catégorie qu’aucun cookie de votre site n’utilise, le panneau des détails montre quand même cette catégorie sur les pages où se trouve le script.

<button type="button">Allow YouTube videos</button>

Un cadre que vous écrivez à la main avec data-cr-src reste vide jusqu’au consentement. La courte demande avec un bouton n’apparaît que dans les cadres que Cookie Rocks retient lui-même. Pour l’obtenir, gardez le src normal d’un fournisseur connu, et laissez Cookie Rocks retenir le cadre.

fin du oui
Le oui dure des mois. Le cookie peut rester des années.Durée des cookies →
Vous écrivez le code ?Durée des cookies : bonnes pratiques pour les développeurs →
Vous faites une extension ou un thème ?Vérifiez les noms de vos cookies et de vos clés de stockage avant de publier. Un nom déjà pris, ou trop générique, est classé et bloqué avec celui d’un autre.
Pour les développeurs d’extensions et de thèmes →