Documentation

Documentation CookiePilot

Le guide complet pour installer, configurer et intégrer CookiePilot a votre site.

Choisissez votre méthode d’installationEssayer la démo interactive

Introduction

CookiePilot est une plateforme de gestion du consentement (CMP), conforme au RGPD, à l'article 82 de la loi Informatique et Libertés (transposant la directive ePrivacy) et à Google Consent Mode v2. En France, le respect de ces règles est contrôlé par la CNIL.

À qui ça s'adresse

  • Propriétaires de sites : déploiement sans aucune ligne de code.
  • Développeurs : API, événements, intégrations GTM.
  • Agences : marque blanche, gestion multi-domaines.

Démarrage rapide

Étape 1 : Inscription

  1. Créez un compte sur app.cookiepilot.io/register.
  2. Ajoutez votre domaine dans le tableau de bord et copiez la clé API (format cp_live_...).

Étape 2 : Installer le code

Une installation directe, ce sont deux scripts dans le <head>, dans cet ordre.

Étape 2a : Consentement par défaut (stub inline). Collez-le en premier, avant tout autre script (cookiepilot.js, GA, GTM, balises publicitaires et de suivi) :

<script>"use strict";(function(){window.dataLayer=window.dataLayer||[];var d={ad_storage:"denied",ad_user_data:"denied",ad_personalization:"denied",analytics_storage:"denied",functionality_storage:"denied",personalization_storage:"denied",security_storage:"granted",wait_for_update:500},h=false;try{for(var i=0;i<window.dataLayer.length;i++){var x=window.dataLayer[i];if(x&&x[0]==="consent"&&x[1]==="default"){h=true;break}}}catch(err){}if(!h&&window.dataLayer.length)window.dataLayer.unshift(["consent","default",d]);window.gtag=function(){window.dataLayer.push(arguments)};if(!h)window.gtag("consent","default",d);var a=document.cookie.match(/(^|)cookiepilot_consent=([^;]+)/);if(a){try{var e=JSON.parse(decodeURIComponent(a[2]));window.gtag("consent","update",{analytics_storage:e.analytics?"granted":"denied",ad_storage:e.marketing?"granted":"denied",ad_user_data:e.marketing?"granted":"denied",ad_personalization:e.marketing?"granted":"denied",functionality_storage:e.preferences?"granted":"denied",personalization_storage:e.preferences?"granted":"denied",security_storage:"granted"})}catch(err){}}})();</script>

Ce snippet inline met immédiatement chaque catégorie sur denied (avec wait_for_update: 500), si bien que l'état par défaut de Google Consent Mode v2 est prêt avant tout autre chargement. Pour un visiteur qui revient, il lit le consentement enregistré directement dans le cookie et déclenche un consent update.

Étape 2b : Script du bandeau. Ajoutez-le juste après le stub inline :

<!-- CookiePilot -->
<script async src="https://cdn.cookiepilot.io/cookiepilot.js" data-cpkey="TWOJ_KLUCZ"></script>

Étape 3 : Configurer le bandeau

Dans le tableau de bord : Domaine → Configuration → Apparence :

  • position du bandeau (haut, bas, modale),
  • couleurs et textes,
  • un bouton flottant « Paramètres des cookies » pour les visiteurs qui reviennent.

Intégration Google Tag Manager

Via GTM, vous installez CookiePilot avec une seule balise HTML personnalisée qui fixe l'état de consentement par défaut et charge le bandeau au tout premier stade de GTM. Vous n'avez besoin ni d'un fichier stub distinct ni d'une seconde balise.

Dans GTM, créez une balise HTML personnalisée (Balises → Nouveau → HTML personnalisé) et collez :

<script>"use strict";
(function() {
window.dataLayer=window.dataLayer||[];var d={ad_storage:"denied",ad_user_data:"denied",ad_personalization:"denied",analytics_storage:"denied",functionality_storage:"denied",personalization_storage:"denied",security_storage:"granted",wait_for_update:500},h=false;try{for(var i=0;i<window.dataLayer.length;i++){var x=window.dataLayer[i];if(x&&x[0]==="consent"&&x[1]==="default"){h=true;break}}}catch(err){}if(!h&&window.dataLayer.length)window.dataLayer.unshift(["consent","default",d]);window.gtag=function(){window.dataLayer.push(arguments)};if(!h)window.gtag("consent","default",d);var a=document.cookie.match(/(^|)cookiepilot_consent=([^;]+)/);if(a){try{var e=JSON.parse(decodeURIComponent(a[2]));window.gtag("consent","update",{analytics_storage:e.analytics?"granted":"denied",ad_storage:e.marketing?"granted":"denied",ad_user_data:e.marketing?"granted":"denied",ad_personalization:e.marketing?"granted":"denied",functionality_storage:e.preferences?"granted":"denied",personalization_storage:e.preferences?"granted":"denied",security_storage:"granted"})}catch(err){}}
var s = document.createElement('script');
s.src = 'https://cdn.cookiepilot.io/cookiepilot.js?cpkey=' + encodeURIComponent('TWOJ_KLUCZ');
document.head.appendChild(s);
})();
</script>

Déclencheur : Consent Initialization - All Pages. La balise doit se déclencher une fois par page. Les balises Google (GA4, Google Ads), Facebook Pixel et les autres balises marketing n'utilisent PAS le déclencheur Consent Initialization ; elles se déclenchent plus tard (Consent Checks ou un déclencheur dépendant du consentement). Enregistrez la balise et publiez le conteneur GTM.

Ordre et déclencheurs

OrdreBaliseDéclencheur
1CookiePilot - Consent Init + BannerConsent Initialization - All Pages
2GA4, Google Ads, UETAll Pages (Consent Mode gère lui-même le consentement)
3Facebook Pixel, TikTok, LinkedIn, etc.Custom Event cookiepilot_consent_update + condition de consentement (voir ci-dessous)

Balises hors Google (Facebook Pixel, TikTok, LinkedIn)

Google Consent Mode ne couvre que les balises Google. Pour tout autre script, le widget pousse un événement dans le dataLayer à chaque changement de consentement :

dataLayer.push({
  event: 'cookiepilot_consent_update',
  cookiepilot_consent: {
    necessary: true,
    analytics: true,
    marketing: true,
    preferences: false
  }
});

L'événement se déclenche aussi à chaque visite d'un utilisateur qui revient (quand le widget lit le cookie de consentement), si bien que le déclencheur GTM fonctionne à chaque visite, pas seulement lors de la première décision.

Schéma commun (à faire une seule fois)

Vous configurez ces trois éléments une seule fois, puis vous les réutilisez pour toutes les balises hors Google.

  1. Déclencheur (Déclencheurs → Nouveau → Custom Event) : nom de l'événement cookiepilot_consent_update. Aucune condition, pas de « Once per page » (la balise doit pouvoir se déclencher à nouveau après un changement de décision).
  2. Data Layer Variable pour chaque catégorie que vous utilisez :
    • Nom cookiepilot_consent.marketing → variable p. ex. dlv.cp_marketing
    • Nom cookiepilot_consent.analytics → variable p. ex. dlv.cp_analytics
    • Nom cookiepilot_consent.preferences → variable p. ex. dlv.cp_preferences
  3. Trigger Group ou une condition sur le déclencheur : dlv.cp_marketing equals true (pour les balises marketing) ou le champ concerné.

Dans chacun des exemples ci-dessous, le Trigger est le même Custom Event auquel on a ajouté une condition sur la bonne variable.

Facebook Pixel

Balise dans GTM : Tags → New → Custom HTML.

<script>
!function(f,b,e,v,n,t,s){if(f.fbq)return;n=f.fbq=function(){n.callMethod?
n.callMethod.apply(n,arguments):n.queue.push(arguments)};if(!f._fbq)f._fbq=n;
n.push=n;n.loaded=!0;n.version='2.0';n.queue=[];t=b.createElement(e);t.async=!0;
t.src=v;s=b.getElementsByTagName(e)[0];s.parentNode.insertBefore(t,s)}(window,
document,'script','https://connect.facebook.net/en_US/fbevents.js');
fbq('init', 'YOUR_PIXEL_ID');
fbq('track', 'PageView');
</script>
  • Déclencheur : cookiepilot_consent_update + condition dlv.cp_marketing equals true.
  • Options de déclenchement de la balise : Once per page.

En option, pour une conformité complète avec Facebook Limited Data Use, ajoutez une seconde balise qui appelle fbq('consent','revoke') avec le déclencheur dlv.cp_marketing equals false.

TikTok Pixel

Balise dans GTM : Tags → New → Custom HTML.

<script>
!function (w, d, t) {
  w.TiktokAnalyticsObject=t;var ttq=w[t]=w[t]||[];ttq.methods=["page","track","identify","instances","debug","on","off","once","ready","alias","group","enableCookie","disableCookie","holdConsent","revokeConsent","grantConsent"],ttq.setAndDefer=function(t,e){t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}};for(var i=0;i<ttq.methods.length;i++)ttq.setAndDefer(ttq,ttq.methods[i]);ttq.instance=function(t){for(var e=ttq._i[t]||[],n=0;n<ttq.methods.length;n++)ttq.setAndDefer(e,ttq.methods[n]);return e},ttq.load=function(e,n){var r="https://analytics.tiktok.com/i18n/pixel/events.js",o=n&&n.partner;ttq._i=ttq._i||{},ttq._i[e]=[],ttq._i[e]._u=r,ttq._t=ttq._t||{},ttq._t[e]=+new Date,ttq._o=ttq._o||{},ttq._o[e]=n||{};n=document.createElement("script");n.type="text/javascript",n.async=!0,n.src=r+"?sdkid="+e+"&lib="+t;e=document.getElementsByTagName("script")[0];e.parentNode.insertBefore(n,e)};
  ttq.load('YOUR_TIKTOK_PIXEL_ID');
  ttq.grantConsent();
  ttq.page();
}(window, document, 'ttq');
</script>
  • Déclencheur : cookiepilot_consent_update + condition dlv.cp_marketing equals true.
  • Options de déclenchement de la balise : Once per page.

ttq.grantConsent() est la nouvelle API de TikTok (introduite en 2024). Sans elle, TikTok reçoit des données hachées sans consentement, ce qui viole les conditions d'utilisation.

LinkedIn Insight Tag

<script type="text/javascript">
_linkedin_partner_id = "YOUR_LINKEDIN_PARTNER_ID";
window._linkedin_data_partner_ids = window._linkedin_data_partner_ids || [];
window._linkedin_data_partner_ids.push(_linkedin_partner_id);
</script>
<script type="text/javascript">
(function(l) {
if (!l){window.lintrk = function(a,b){window.lintrk.q.push([a,b])};
window.lintrk.q=[]}
var s = document.getElementsByTagName("script")[0];
var b = document.createElement("script");
b.type = "text/javascript";b.async = true;
b.src = "https://snap.licdn.com/li.lms-analytics/insight.min.js";
s.parentNode.insertBefore(b, s);})(window.lintrk);
</script>
  • Déclencheur : cookiepilot_consent_update + condition dlv.cp_marketing equals true.
  • Options de déclenchement de la balise : Once per page.

Hotjar

<script>
(function(h,o,t,j,a,r){
  h.hj=h.hj||function(){(h.hj.q=h.hj.q||[]).push(arguments)};
  h._hjSettings={hjid:YOUR_HOTJAR_ID,hjsv:6};
  a=o.getElementsByTagName('head')[0];
  r=o.createElement('script');r.async=1;
  r.src=t+h._hjSettings.hjid+j+h._hjSettings.hjsv;
  a.appendChild(r);
})(window,document,'https://static.hotjar.com/c/hotjar-',".js?sv=");
</script>
  • Déclencheur : cookiepilot_consent_update + condition dlv.cp_analytics equals true.
  • Options de déclenchement de la balise : Once per page.

Hotjar relève d'analytics, pas de marketing (il mesure des comportements, pas de la publicité). Vérifiez votre propre politique cookies : certaines entreprises classent Hotjar différemment.

Microsoft Clarity

<script type="text/javascript">
(function(c,l,a,r,i,t,y){
  c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
  t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
  y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
})(window, document, "clarity", "script", "YOUR_CLARITY_PROJECT_ID");
</script>
  • Déclencheur : cookiepilot_consent_update + condition dlv.cp_analytics equals true.
  • Options de déclenchement de la balise : Once per page.

Pinterest Tag

<script>
!function(e){if(!window.pintrk){window.pintrk = function () {
window.pintrk.queue.push(Array.prototype.slice.call(arguments))};var
n=window.pintrk;n.queue=[],n.version="3.0";var
t=document.createElement("script");t.async=!0,t.src=e;var
r=document.getElementsByTagName("script")[0];
r.parentNode.insertBefore(t,r)}}("https://s.pinimg.com/ct/core.js");
pintrk('load', 'YOUR_PINTEREST_TAG_ID');
pintrk('page');
</script>
  • Déclencheur : cookiepilot_consent_update + condition dlv.cp_marketing equals true.
  • Options de déclenchement de la balise : Once per page.

Microsoft Ads (UET)

UET prend en charge Google Consent Mode depuis fin 2023 : vous n'avez pas besoin d'un déclencheur Custom Event. Ajoutez la balise de façon standard (All Pages, Once per page) et UET lit lui-même ad_storage depuis GCM, que le widget positionne.

Correspondance des catégories (récapitulatif)

BaliseCatégorieChamp dans cookiepilot_consent
Facebook Pixelmarketingmarketing
TikTok Pixelmarketingmarketing
LinkedIn Insightmarketingmarketing
Pinterestmarketingmarketing
Hotjaranalyticsanalytics
Microsoft Clarityanalyticsanalytics
Mixpanel, Amplitudeanalyticsanalytics
Intercom, Drift, Crisppréférencespreferences
GA4, Google Ads, UET(GCM, sans déclencheur)gère par gtag('consent','update')

Référence API

CookiePilot expose l'objet window.CookiePilot :

MéthodeDescription
CookiePilot.getConsent()L'état de consentement actuel, ou null si aucune décision n'a été prise.
CookiePilot.acceptAll()Consentement à toutes les catégories.
CookiePilot.rejectAll()Refuse tout sauf necessary.
CookiePilot.updateConsent(partial)Met à jour les catégories choisies, p. ex. { analytics: true }.
CookiePilot.showSettings()Ouvre la modale de préférences.
CookiePilot.hideSettings()Ferme la modale de préférences.
CookiePilot.showMyConsent() / hideMyConsent()Affiche/masque le bouton flottant.

Exemple

const consent = CookiePilot.getConsent();
// { necessary: true, analytics: true, marketing: false, preferences: false }

CookiePilot.updateConsent({ analytics: true });

document.getElementById('cookie-settings').addEventListener('click', () => {
  CookiePilot.showSettings();
});

Lien « Gérer les cookies » dans le pied de page

<a href="#" onclick="CookiePilot.showSettings(); return false;">Gerer les cookies</a>

Événements JavaScript

Le widget émet un événement natif cookiepilot:consent sur window. L'écouteur doit être enregistré avant le chargement du widget si vous voulez capter l'événement pour un visiteur qui revient (l'émission se déclenche immédiatement dès le démarrage du widget) :

<script>
  window.addEventListener('cookiepilot:consent', (e) => {
    if (e.detail.marketing) {
      fbq('init', 'YOUR_PIXEL_ID');
    }
  });
</script>
<script src="https://cdn.cookiepilot.io/cookiepilot.js" data-cpkey="TWOJ_KLUCZ"></script>

e.detail contient la même charge utile que getConsent(). Pour les intégrations basées sur GTM, utilisez plutôt l'événement dataLayer décrit plus haut, car le dataLayer est un tableau persistant et GTM traite aussi les événements passés.


Catégories de consentement

CatégorieDescriptionPar défaut
necessaryRequis pour le fonctionnement du siteToujours actif
analyticsStatistiques et analytiqueConsentement requis
marketingPublicité et remarketingConsentement requis
preferencesPersonnalisation, langueConsentement requis
Catégorie CookiePilotChamps Consent Mode
analyticsanalytics_storage
marketingad_storage, ad_user_data, ad_personalization
preferencesfunctionality_storage, personalization_storage
(toujours)security_storage: granted

La version 2 a ajouté ad_user_data et ad_personalization (requis depuis mars 2024 dans l'UE/EEE pour la publicité Google).

ParamètreDescription
ad_storageCookies publicitaires
analytics_storageCookies analytiques
ad_user_dataEnvoi de données utilisateur à Google
ad_personalizationPersonnalisation des publicités
functionality_storageCookies fonctionnels
personalization_storageCookies de personnalisation
security_storageToujours granted

Comment ça marche :

  1. Le stub met chaque champ sur denied de façon synchrone, avec wait_for_update: 500.
  2. Après la décision de l'utilisateur, le widget déclenche gtag('consent', 'update', {...}) en s'appuyant sur la correspondance ci-dessus.
  3. Pour un visiteur qui revient, l'étape 2 se déclenche immédiatement dès le démarrage du widget, sur la base du cookie.

Configuration de l'apparence

Dans le tableau de bord : Domaine → Configuration :

  • Apparence : position, couleurs, mise en page (BAR / BOX / MODAL).
  • Textes : titre, description, libellés des boutons, descriptions des catégories. 13 langues (EN, PL, DE, FR, ES, IT, NL, PT, SV, CS, RO, EL, HU).
  • Bouton de consentement : un bouton flottant « Paramètres des cookies » affiché après la première décision (en bas à gauche/droite).
  • CSS personnalisé : un champ pour vos propres styles. Le widget s'affiche dans le Shadow DOM, si bien que les sélecteurs CSS du document principal ne fonctionneront pas. Utilisez uniquement ce champ.

Accessibilité (WCAG 2.1 AA)

  • ✅ Navigation au clavier (Tab, Shift+Tab, Enter, Escape).
  • ✅ Étiquettes ARIA, rôle="dialog", aria-modal.
  • ✅ Piège de focus dans la modale.
  • ✅ Prise en charge des lecteurs d'écran (live régions au changement d'état).
  • ✅ Design responsive.

Intégrations

WordPress

Nous avons une extension officielle : CookiePilot sur WordPress.org.

  1. Admin WordPress → Extensions → Ajouter → recherchez « CookiePilot ».
  2. Installez et activez.
  3. Réglages → CookiePilot → collez la clé API du tableau de bord.

L'extension insère elle-même le stub et la balise dans le <head> (dans le bon ordre, avant les autres scripts) et fournit un shortcode [cookiepilot_settings] pour un lien « Gérer les cookies » dans le pied de page.

Si vous préférez ne pas utiliser l'extension, servez-vous de « Insert Headers and Footers » et collez le snippet de l'étape 2 du Démarrage rapide dans la section Header.

Shopify

  1. Boutique → Thèmes → Modifier le code.
  2. Dans theme.liquid, collez le snippet avant </head>.

Next.js

// app/layout.tsx
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <Script
          src="https://cdn.cookiepilot.io/cookiepilot.js"
          data-cpkey="TWOJ_KLUCZ"
          strategy="beforeInteractive"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

strategy="beforeInteractive" garantit que le script du bandeau s'exécute tôt. N'oubliez pas que le stub inline de l'étape 2a (consentement par défaut) s'ajoute séparément, dans le <head> avant ce script, par exemple via next/script avec dangerouslySetInnerHTML ou directement dans app/layout.tsx.


FAQ

Le script ralentit-il le site ?

Le script est léger et se charge de manière asynchrone, il ne bloque donc pas le rendu. L’impact réel sur les Core Web Vitals dépend aussi de la configuration de votre site et des autres scripts.

Combien de temps le consentement est-il conserve ?

Le cookie de décision de l'utilisateur : 365 jours par défaut (configurable dans le tableau de bord). Les événements analytiques : 2 ans (TTL ClickHouse).

Oui. Le widget lit le cookie au démarrage et pousse l'événement dans le dataLayer. Le déclencheur Custom Event dans GTM se déclenche à chaque visite, pas seulement lors de la première décision.

Où signaler un problème ?

kontakt@cookiepilot.io ou le chat dans le tableau de bord.


Checklist de tests après déploiement

Une fois CookiePilot installe, vérifiez la configuration avant de lancer des campagnes publicitaires.

1. Test avant que l'utilisateur ne donne son consentement

  1. Ouvrez le site en navigation privée et effacez les cookies du domaine.
  2. Ouvrez DevTools → Network et rechargez la page.
  3. Avant de cliquer sur le consentement, confirmez que :
    • aucun cookie analytique/marketing n'est créé, p. ex. _ga, _gcl_*, _fbp, _ttp,
    • les balises marketing n'envoient pas de requêtes vers Meta/TikTok/LinkedIn avant le consentement marketing,
    • le dataLayer porte l'état par défaut denied pour ad_storage, ad_user_data, ad_personalization et analytics_storage.

2. Test après acceptation du consentement

  1. Cliquez sur « Tout accepter ».
  2. Dans DevTools, vérifiez que l'événement cookiepilot_consent_update est apparu.
  3. Pour les balises Google, vérifiez dans GTM Preview / Tag Assistant que Consent Mode est passé à l'état granted pour les catégories concernées.
  4. Pour GA4, vérifiez dans DebugView que les événements commencent à arriver après le consentement.
  5. Pour Meta Pixel / TikTok / LinkedIn, vérifiez que les balises ne se déclenchent qu'après l'événement cookiepilot_consent_update et la condition de consentement marketing.

3. Test du refus du consentement

  1. Effacez les cookies et rechargez la page.
  2. Cliquez sur « Tout refuser ».
  3. Confirmez que les cookies et requêtes marketing ne sont toujours pas déclenchés.
  4. Confirmez que les fonctionnalités essentielles du site continuent de marcher.

4. Erreurs fréquentes

  • La balise GA4/Google Ads se déclenche sur Consent Initialization au lieu d'un déclencheur ultérieur.
  • Le Meta Pixel ou le TikTok Pixel n'a pas de condition sur cookiepilot_consent.marketing.
  • Un ancien traceur code en dur est encore présent dans le <head> avant CookiePilot.
  • La documentation ou le modèle contient encore une URL de script obsolète ou un ancien attribut d'identifiant au lieu de l'actuel cookiepilot.js avec data-cpkey.

Preuve de consentement, exports et DSAR

CookiePilot enregistre les événements de consentement pour que vous puissiez reconstituer le contexte de la décision d'un visiteur. Un enregistrement peut inclure l'horodatage de l'événement, son type, le domaine, l'URL de la page ou de la source, la version du consentement, les catégories et la consent string lorsqu'elle est disponible, l'adresse IP anonymisée, le hash du user-agent, le type d'appareil et le navigateur.

Exports

  • Preuve de consentement d'un visiteur : JSON, CSV ou HTML imprimable.
  • Journal d'audit du domaine : CSV ou JSON pour une plage de dates choisie.
  • Les exports sont limités à votre organisation et aux domaines auxquels vous avez accès.

Processus DSAR

Un Owner ou un Admin peut lancer une demande d'accès aux données depuis une ligne de consentement ou depuis la page DSAR du panneau. Le panneau retrouve les événements du visiteur, affiche la plage et vous permet de télécharger les fichiers de preuve. Une demande de suppression exige un motif et est consignée dans le journal d'activité de l'organisation.

Limites

Les exports d'audit de domaine utilisent la plage de dates choisie et peuvent être tronqués pour de très grands ensembles de résultats. La durée de conservation du journal de consentement suit le plan actif et la politique du compte, si bien que la documentation publique ne promet pas un nombre d'années fixe.