@wavenet/cookie-law
Version:
À l'ère du _RGPD_, faut-il expliquer le besoin d'une bannière de cookies ? _Cookie law_ vous permet d'ajouter une bannière invitant le visiteur à accepter ou refuser certains cookies sur votre site.
204 lines (160 loc) • 14.5 kB
Markdown
# Cookie law
## Introduction
À l'ère du _RGPD_, faut-il expliquer le besoin d'une bannière de cookies ?
_Cookie law_ vous permet d'ajouter une bannière invitant le visiteur à accepter ou refuser certains cookies sur votre
site.
## Installation
### 1. Yarn
Ajoutez le package à votre projet.
Rendez-vous à la racine du projet où se trouve votre _package.json_ et exécutez :
```shell
yarn add @wavenet/cookie-law
```
### 2. Composant
Appeler le composant `<wvn-cookie-law>` dans votre code.
Voici un exemple :
```tsx
import "@wavenet/cookie-law/dist/cookielaw";
export function CookieLaw() {
return (
<wvn-cookie-law>
<script type="application/json">
{`{
"locale": "fr",
"links": {
"cookiePolicy": "/cookies/"
},
"licence": true,
"changePreferences": "#cookie-preferences",
"isOptOut": false,
"defaultCheckboxState": false,
"categories": [
"introduction",
"strictly-necessary",
"more_information"
],
"storage": "cookie"
}`}
</script>
</wvn-cookie-law>
);
}
```
### 3. Configuration
À l'intérieur de la balise `<script>`, vous devez fournir un `json` avec les paramètres de votre bannière.
Vous pouvez aussi travailler avec un fichier `json` au lieu d'injecter le `json` dans le `<script>`.
Plus d'informations sur comment configurer dans la partie _Configuration_ ci-dessous.
### 4. Design
Plusieurs variables sont mises à votre disposition, mais il est possible aussi d'atteindre certains _tags HTML_ via
des `part`.
### 5. Catégoriser les scripts
Sur chaque balise `<script>`, veillez à :
- donner le type de catagorie concerné via `data-consent` ;
- mettre le type du script à `text/plain`.
_Cookie law_ va alors transformer les _scripts_ en _js_ dès que le visiteur aura accepter la catégorie associée.
Exemple avec _Google analytics_ :
```html
<script type="text/plain" data-consent="tracking" async src="https://www.googletagmanager.com/gtag/js?id=123"></script>
<script type="text/plain" data-consent="tracking">
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', '{{ domainConfig.field_t_ga.0.value }}');
</script>
```
Dans ce cas-ci, il faut que le visiteur accepte les cookies de _tracking_.
## Configuration
| Nom du paramètre | Type | Description |
|------------------------|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| _acceptRejectAll_ | _boolean_ | Cette option permet d'ajouter un bouton pour refuser tous les cookies non essentiels, au niveau de la bannière des cookies et au niveau de la modale. |
| _categories_ | _object_ | Ce sont les catégories des cookies. Ils sont listés dans la _modal_ des préférences et sont utilisés pour sélectionner les scritps à autoriser/bloquer en fonction des préférences du visiteur. Plus d'info ci-dessous. |
| _changePreferences_ | _string_ | Cette option accueille un sélecteur css. N'importe quel _tag HTML_ ayant ce selecteur permettra d'ouvrir au clic la _modal_ des préférences et ainsi permettre au visiteur de changer ses préférences. |
| _cookieMaxAge_ | _number_ | Cette option permet de gérer le délai d'expiration. Vous devez fournir le temps en secondes. Par défaut, il suit les recommandations RGPD et vaut 6 mois (182.5 jours exactement). |
| _defaultCheckboxState_ | _boolean_ | Chaque catégorie de cookies facultatives peuvent être acceptée ou refusée par le visiteur via la _modal_ des préférences où chaque catégorie est (dé)cochable via une _checkbox_. La valeur à _false_, cela signifie que par défaut ces catégories non obligatoires sont décochées. |
| _isOptOut_ | _boolean_ | |
| _labels_ | _Record<string, string>_ | Cette option permet de surchager les textes. En effet, une série de textes est présent par défaut en Anglais, Français, Néerlandais et Allemand. Si vous voulez altérer ces textes, vous devez retrouver le nom machine dudit texte et le remplacer. Veillez à utiliser du _markdown_. L'_HTML_ est autorisé, mais vous risquez de perdre le design des `<a>` si vous n'ajoutez pas vous-mêmes des `part`. |
| _licence_ | _boolean_ | Si cette option est à _false_, on affiche le _copyright_ de _Wavenet_ dans la _modal_ des préférences. |
| _links_ | _{cookiePolicy: string}_ | Cette option permet de surcharger le lien vers la politique des cookies sans surcharger le texte via les _labels_ (cf. ci-dessus). |
| _locale_ | _string_ | La langue du site. A priori vous n'en aurez pas besoin si vous avez fait ceci `<html lang="fr">`. En effet, _Cookie law_ peut détecter la langue du site. |
| _scriptRestoreMode_ | _string_ | Les scripts, préalablement typés _text/plain_, sont activés après le consentement. Par défaut, on remplace le script par lui-même dans sa version active. Vous pouvez choisir de conserver le script _text/plain_ et le dupliquez en version active. Vous pourriez en avoir besoin dans le cadre de projets utilisant un framework comme react pour résoudre des problèmes de réhydratation. |
| _storage_ | _string_ | On attend _local_ ou _cookie_. Par défaut, c'est _local_. Dans le premier cas, les catégories de cookies sélectionnées seront enregistrées dans les _localstorage_ du navigateur du visteur ; dans le second cas, dans ses cookies. |
### Catégories de cookie
#### Catégories de cookie existantes
Voici la liste des catégories existantes :
- _introduction_
- _strictly-necessary_
- _functionality_
- _tracking_
- _more_information_
Vous pouvez donc simplement envoyer un _array_ avec ces mots-clés pour choisir les onglets à afficher dans la _modal_
des préférences et leur ordre.
Exemple :
```json
{
"categories": [
"introduction",
"strictly-necessary",
"functionality",
"more_information"
]
}
```
#### Surcharger les catégories existantes
Si vous voulez modifier une des propriétés d'un cookie, vous devrez lui passer non plus une simple _string_, mais un
_object_ contenant le code du cookie et la/les valeurs que vous voulez modifier.
Exemple :
```json
{
"categories": [
"introduction",
{
"code": "strictly-necessary",
"cookies": {
"Coockie #1": "https://www.wavenet.be/cookies/"
}
},
"functionality",
"more_information"
]
}
```
#### Propriétés d'une catégorie
| Nom de la popriété | Type | Description |
|--------------------|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| _code_ | _string_ | Comme expliqué ci-dessus, cela va permettre d'identifier le cookie à altérer. |
| _title_ | _string_ | Titre de l'onglet dans la _modal_ des préférences. |
| _tabTitle_ | _string_ | Libellé du bouton de l'onglet dans la _modal_ des préférences. |
| _description_ | _string[]_ | Contenu de l'onglet dans la _modal_ des préférences. Veillez à utiliser du _markdown_. L'_HTML_ est autorisé, mais vous risquez de perdre le design des `<a>` si vous n'ajoutez pas vous-mêmes des `part`. |
| _cookies_ | _Record<string, string>_ | Liste des cookies de la catégorie. Chaque cookie est un lien. |
| _consent_ | _boolean_ | Valeur à _true_, si c'est une catégorie de cookie ; à _false_, si vous voulez juste avoir un nouvel onglet dans la _modal_ des préférences, comme les onglets _introduction_ ou _plus d'informations_. |
| _required_ | _boolean_ | Valeur à _true_, si le visiteur ne peut pas refuser cette catégorie. Typiquement la catégorie _Strictement nécessaire_. |
| _cleaning_ | _string[]_ | Liste des cookies à supprimer. En effet, si le visiteur change ses préférences, des cookies ont déjà été enregistrés sur son navigateur. Le sous-domaine courant est pris en compte, mais aussi ses parents. Ex : Les cookies sur `www.mon-site.be` et `.mon-site.be` seront affectés. |
#### Catégorie presonnalisé
Remplissez simplement les propriétés ci-dessus avec un code unique.
```json
{
"categories": [
"introduction",
{
"code": "foo-bar",
"title": "Nunc ante nunc, luctus id nisi eget...",
"tabTitle": "Nunc ante nunc",
"description": [
"Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
"In in tempus sapien, in tempor libero.",
"Aliquam lobortis venenatis odio sit amet egestas.",
"Ut nibh nulla, feugiat eget commodo id, fermentum sit amet odio."
],
"consent": true,
"required": false
},
"more_information"
]
}
```
Utilisez ensuite ce code unique sur vos _scritps_.
```html
<script type="text/plain" data-consent="foo-bar">
console.log('Cookie foo bar is allowed.');
</script>
```