← Retour à l’accueil

Documentation développeurs

Le script Nodbar affiche la bannière, retient les outils de mesure et de publicité jusqu’à l’accord du visiteur et garde la preuve de chaque choix. Cette page explique comment votre code s’y branche : balises à marquer, API JavaScript, événements, types TypeScript et exemples pour React, Vue et Next.js.

Installer le script

Créez votre bannière depuis l’adresse de votre site : le tableau de bord donne la ligne exacte, avec la clé du site. Placez-la en premier dans <head>, sans async ni defer : elle doit s’exécuter avant les autres scripts pour pouvoir les retenir.

<head>
  <script src="https://cdn.nodbar.com/s/VOTRE-CLE.js"></script>
  <!-- vos autres scripts ensuite -->
</head>

Les extensions WordPress, Shopify, PrestaShop, Joomla, Drupal et Magento, et le modèle Google Tag Manager, posent cette ligne pour vous. Votre assistant de code (Claude Code, Cursor…) peut aussi l’installer : la page Mise en ligne du tableau de bord lui donne la consigne complète.

La bannière parle la langue de la page (l’attribut lang de <html>), sinon celle du navigateur, parmi les langues de votre bannière. Si votre application change de langue sans recharger la page, mettez à jour document.documentElement.lang : la bannière, la liste des cookies et les encarts des vidéos suivent aussitôt, et le choix du visiteur est enregistré dans sa nouvelle langue.

Si votre site envoie une politique de sécurité du contenu (en-tête Content-Security-Policy), ajoutezhttps://cdn.nodbar.com à script-src (le script) et à connect-src (l’envoi de la preuve de consentement). La bannière n’a pas besoin de 'unsafe-inline' dansstyle-src : elle garde son apparence avec une politique stricte, à nonce ou à empreinte.

Blocage automatique ou manuel

Par défaut, Nodbar bloque de lui-même les outils qu’il connaît (scripts, pixels, iframes, cookies) tant que leur catégorie n’est pas acceptée. Le réglage « Qui bloque les outils avant l’accord ? » du tableau de bord propose aussi un mode manuel : Nodbar ne bloque plus rien de lui-même, et seules les balises marquées ci-dessous et le code passé par Nodbar.when attendent l’accord. Google Consent Mode, les preuves et la bannière restent identiques. Dans les deux cas, l’analyse de votre site vérifie que rien ne part avant l’accord.

Marquer les balises

Même en blocage automatique, le navigateur télécharge un <script src> écrit dans le HTML avant tout JavaScript, et une <iframe src> contacte son service aussitôt. Marquez-les : rien ne part avant l’accord, et Nodbar les lance au moment où le visiteur accepte.

Scripts : type="text/plain" et data-nodbar avec la catégorie, analytics,marketing ou functional. Ne marquez pas les scripts nécessaires au site (paiement, panier, sécurité).

<script type="text/plain" data-nodbar="analytics"
  src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX"></script>

<script type="text/plain" data-nodbar="marketing">
  fbq('init', '123456789')
</script>

Iframes (vidéos, cartes, widgets) : renommez src en data-nodbar-src. Nodbar retrouve le service et sa catégorie d’après l’adresse et affiche à sa place un encart « Accepter et afficher », à la même taille. Pour un service qu’il ne connaît pas, ajoutez data-nodbar ; sans lui, l’iframe se charge tout de suite.

<iframe data-nodbar-src="https://www.youtube-nocookie.com/embed/VIDEO"
  width="560" height="315" title="Notre vidéo"></iframe>

<!-- Service que Nodbar ne connaît pas : précisez la catégorie -->
<iframe data-nodbar-src="https://widget.exemple.com/carte" data-nodbar="functional"></iframe>

API JavaScript

Le script expose window.Nodbar :

MéthodeCe qu’elle fait
when(catégorie, fn)Exécute fn une seule fois : tout de suite si la catégorie est acceptée, sinon au moment où le visiteur l’accepte. Une erreur dans fn est affichée dans la console sans gêner les autres. Renvoie une fonction qui annule fn tant qu’elle n’a pas été exécutée.
onChange(fn)Appelle fn avec les catégories accordées après chaque choix, et au chargement quand un choix est déjà enregistré, si fn est inscrite pendant le démarrage du script (ou par la ligne d’attente). Renvoie une fonction qui désinscrit fn, à appeler quand votre composant disparaît.
getConsent()Les catégories accordées, necessary compris.
getConsentId()L’identifiant de la preuve de consentement du visiteur, une fois son choix fait : à lui communiquer s’il le demande.
open()Ouvre le panneau des préférences, pour votre propre bouton « Gérer les cookies ».

Les catégories sont necessary (toujours accordée), analytics,marketing et functional. Quand le visiteur retire un accord, la page se recharge : un script déjà lancé ne peut pas être arrêté.

Lancer un outil chargé par votre code

Un outil installé par npm ou lancé par votre application n’a pas de balise à marquer : enveloppez son initialisation dans Nodbar.when.

Nodbar.when('analytics', () => {
  // ne s'exécute qu'une fois, après l'accord du visiteur
  posthog.init('phc_XXXXXXXX', { api_host: 'https://eu.i.posthog.com' })
})

Appeler l’API avant le chargement du script

Si votre code peut s’exécuter avant le script Nodbar (script chargé par Google Tag Manager, chargement asynchrone), ajoutez d’abord cette ligne : when, onChange et open sont mis en attente, puis exécutés dès que le script démarre. Les fonctions d’annulation qu’ils renvoient marchent avant comme après ce démarrage.

<script>window.Nodbar=window.Nodbar||{q:[]};['when','onChange','open'].forEach(function(m){Nodbar[m]=Nodbar[m]||function(){var e=[m].concat([].slice.call(arguments));Nodbar.q.push(e);return function(){typeof e.off=='function'?e.off():e.off=1}}})</script>

Lien « Gérer les cookies » et liste des cookies

Tout élément portant data-nodbar-open ouvre les préférences, même ajouté plus tard par votre framework. Sur une page qui affiche un tel lien, la pastille en bas de l’écran n’apparaît plus après le choix : le lien la remplace. Un élément data-nodbar-cookies, sur votre page de politique cookies, se remplit de la liste des cookies du site, à jour à chaque publication.

<a href="#" data-nodbar-open>Gérer les cookies</a>

<div data-nodbar-cookies></div>

Événements

Après chaque choix, et au chargement de la page quand un choix est déjà enregistré, le script émet l’événement nodbar:consent sur window et pousse nodbar_consent dans la couche de données de Google Tag Manager.

window.addEventListener('nodbar:consent', (event) => {
  console.log(event.detail.granted) // ['necessary', 'analytics']
})

// Google Tag Manager : déclencheur « Événement personnalisé » nodbar_consent,
// variable de couche de données nodbar_granted
window.dataLayer.push({ event: 'nodbar_consent', nodbar_granted: ['necessary', 'analytics'] })

Sans rien ajouter, le script transmet aussi le choix à Google Consent Mode v2, Microsoft Clarity, Microsoft Ads, au pixel Meta, à Matomo, à l’API Customer Privacy de Shopify et à la WP Consent API de WordPress.

Types TypeScript

Téléchargez nodbar.d.ts dans votre projet, dans un dossier compris par l’include de votre tsconfig.json : window.Nodbar, ses catégories (NodbarCategory) et l’événement nodbar:consent sont alors typés.

curl -o src/nodbar.d.ts https://nodbar.com/nodbar.d.ts

window.Nodbar est indéfini tant que le script n’a pas démarré, d’où le ?. des exemples. Avec la ligne d’attente, seules when, onChange et open existent avant le démarrage.

Exemples React, Vue et Next.js

React

// useConsent.ts : les catégories accordées, mises à jour à chaque choix
import { useEffect, useState } from 'react'

export function useConsent(): NodbarCategory[] {
  const [granted, setGranted] = useState<NodbarCategory[]>(['necessary'])
  useEffect(() => {
    const update = (event: CustomEvent<NodbarConsentDetail>) => setGranted(event.detail.granted)
    window.addEventListener('nodbar:consent', update)
    const current = window.Nodbar?.getConsent?.()
    if (current) setGranted(current)
    return () => window.removeEventListener('nodbar:consent', update)
  }, [])
  return granted
}

// Analytics.tsx : lance un outil chargé par npm, une seule fois, après l'accord
import { useEffect } from 'react'
import posthog from 'posthog-js'

export function Analytics() {
  // when renvoie une fonction d'annulation : si le composant disparaît avant l'accord,
  // posthog.init n'est plus appelé
  useEffect(() => window.Nodbar?.when('analytics', () => posthog.init('phc_XXXXXXXX')), [])
  return null
}

// Pied de page
<button type="button" data-nodbar-open>Gérer les cookies</button>

Vue

// useConsent.ts
import { onMounted, onUnmounted, ref } from 'vue'

export function useConsent() {
  const granted = ref<NodbarCategory[]>(['necessary'])
  const update = (event: CustomEvent<NodbarConsentDetail>) => {
    granted.value = event.detail.granted
  }
  onMounted(() => {
    window.addEventListener('nodbar:consent', update)
    granted.value = window.Nodbar?.getConsent?.() ?? granted.value
  })
  onUnmounted(() => window.removeEventListener('nodbar:consent', update))
  return granted
}

// main.ts : un outil lancé par l'application
window.Nodbar?.when('analytics', () => {
  /* initialisation de l'outil */
})

Next.js

N’utilisez pas next/script avec afterInteractive ou lazyOnload : le script arriverait trop tard pour retenir les autres.

// app/layout.tsx : le script Nodbar en premier, sans next/script
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="fr">
      <head>
        <script src="https://cdn.nodbar.com/s/VOTRE-CLE.js" />
      </head>
      <body>{children}</body>
    </html>
  )
}

// app/analytics.tsx : composant client, monté dans le layout
'use client'
import { useEffect } from 'react'

export function Analytics() {
  useEffect(
    () =>
      window.Nodbar?.when('analytics', () => {
        /* initialisation de l'outil */
      }),
    [],
  )
  return null
}

Apparence

Les couleurs, polices et arrondis se règlent dans le tableau de bord. Votre feuille de style peut aussi les surcharger par des variables CSS, et viser chaque élément de la bannière par ::part().

nodbar-consent {
  --nodbar-primary: #0b5cff;
  --nodbar-button-radius: 0;
}
nodbar-consent::part(button-accept) {
  letter-spacing: 0.02em;
}

Variables : --nodbar-primary, --nodbar-on-primary, --nodbar-background, --nodbar-text, --nodbar-radius, --nodbar-button-radius, --nodbar-font, --nodbar-heading-font, --nodbar-font-size, --nodbar-button-weight, --nodbar-button-case, --nodbar-shadow.

Parties : panel, banner, preferences, title, body, actions, button, button-reject, button-accept, button-save, link, category, toggle, always-on, close, reopen, backdrop, meta.

Commencer

Collez l’adresse de votre site : Nodbar l’analyse et prépare une bannière conforme, gratuitement.