L'API vous permet d'écouter les changements apportés aux
préférences, via des événements ou des
promesses. Il est également possible d'indiquer
dans le DOM les éléments qui nécessitent un
consentement préalable en leur ajoutant un attribut
data-discreto
.
Pour les balises HTML comme pour les promesses, il est possible
d'utiliser un wilcard (*
) pour faire référence
à un service ou l'une de ses variantes :
service*
vaut ainsi pour service
ou
service-variante
.
Balises HTML
Pour tout objet du DOM autre qu'un <script>
ou une
<iframe>
, définissez dans l'attribut
data-discreto
le code du service requis, et dans l'attribut
data-class
la classe CSS qui sera ajoutée une fois le
consentement obtenu, ou retirée sinon.
Exemple :
Pour afficher un message en cas de refus (en réalité pour le masquer,
hidden
, une fois accepté) :
<div data-discreto="facebookComments" data-class="hidden">
<p>Vous n'avez pas accepté le service <strong>Facebook
Comments</strong>, les commentaires de cet article ne seront pas
visibles.</p>
<nav class="left btns">
<button onclick="discreto.prefs()"
type="button">Préférences</button>
<button onclick="discreto.update('facebookComments', true)"
type="button" class="ok">Accepter</button>
</nav>
</p>
Résultat :
Vous n'avez pas accepté le service Facebook
Comments, les commentaires de cet article ne seront pas
visibles.
Bonjour les commentaires Facebook ! 😁
Vidéos intégrées et liseuses
Pour une <iframe>
, ajoutez le code du service requis
dans l'attribut data-discreto
, et renommez l'attribut
src
contenant l'URL en data-src
. Le chargement
aura lieu une fois le consentement de l'internaute obtenu.
Tant que l'internaute n'a pas accepté, ou s'il refuse, les contenus
des <iframe>
sont remplacés par un court message
explicatif avec un bouton pour éditer les préférences ou pour activer
le service (sur cette page ou pour tout le site).
L'exemple qui suit tire profit du wildcard (*
),
ainsi youtube*
vaut pour youtube
(vidéo
embedded) et youtube-api
(l'API YouTube).
Exemple :
Pour n'afficher une vidéo YouTube qu'après consentement de l'internaute,
adaptez comme suit le code fourni par YouTube :
<iframe src="https://www.youtube.com/embed/S-u6qdeaPoE?autoplay=1"
frameborder="0" allowfullscreen></iframe>
Devient :
<iframe data-discreto="youtube*"
data-src="https://www.youtube.com/embed/S-u6qdeaPoE?autoplay=1"
frameborder="0" allowfullscreen></iframe>
Résultat :
Si le service youtube
n'a pas été inclus dans la
configuration :
🤕
Aucun consentement n'est prévu pour YouTube (embed), cette fenêtre a
été bloquée :
https://www.youtube.com/embed/ID
Afficher tout de même |
Préférences
Si les conditions du service n'ont pas encore été acceptées :
🤔
Acceptez les conditions du service YouTube (embed) pour afficher
cette fenêtre :
https://www.youtube.com/embed/ID
Accepter |
Toujours accepter pour ce site |
Préférences
Si le service a été refusé :
🤫
Vous avez choisi de bloquer les fenêtres YouTube (embed)
Accepter |
Toujours accepter pour ce site |
Préférences
Attention : si l'internaute retire son
consentement par la suite, la fenêtre restera chargée et ne sera pas
masquée.
Chargement de scripts
Certains services nécessitent de placer une balise
<script>
à un (ou plusieurs) endroit(s) de la page.
Procédez comme pour une <iframe>
en ajoutant
l'identifiant du service associé dans l'attribut
data-discreto
, et en renommant l'attribut src
en data-src
.
Contrairement à l'iframe
, aucun message ne sera affiché
avant le consentement de l'internaute, mais vous pouvez ajouter vous-même
un message dans un élément HTML voisin.
Exemple :
Pour appeler un script qui nécessite d'accepter au préalable le service
_chatbot
, et prévoir un message en cas de refus :
<!-- Script chargé une fois le service accepté -->
<script data-discreto="_chatbot" data-src="/chat/bot.js"></script>
<!-- Paragraphe masqué une fois le service accepté -->
<div data-discreto="_chatbot" data-class="hidden" class="warning">
<p>Veuillez accepter les conditions d'utilisation de notre
<strong>Chatbot</strong> pour démarrer une discussion avec un
conseiller.</p>
<nav class="left btns">
<button onclick="discreto.prefs()"
type="button">Préférences</button>
<button onclick="discreto.update('_chatbot', true)"
type="button" class="ok">Accepter</button>
</nav>
</div>
Résultat :
Veuillez accepter les conditions d'utilisation de notre
Chatbot pour démarrer une discussion avec un
conseiller.
Bonjour, comment puis-je vous aider aujourd'hui ?
Attention : comme pour les
<iframe>
, si l'internaute retire son consentement par
la suite, le script ne pourra être déchargé et sera toujours
actif sur la page.
Méthodes
Les méthodes suivantes sont supportées :
start(conf)
- Lancer discreto avec une configuration personnalisée
conf
update(name, on, store)
- Met à jour la préférence pour le service
name
prefs(showHide)
- Affiche/masque les préférences
popup(showHide)
- Affiche/masque la fenêtre
clean()
- Ferme et détruit la fenêtre
Exemples :
discreto.update('youtube', true)
Autorise les iframes YouTube pour cette page
discreto.update('soundcloud', true, true)
Autorise toutes les iframes SoundCloud
discreto.prefs()
Affiche les préférences
Événements
Vous pouvez écouter les événements discreto
et
discreto-service
au niveau du document
pour être informé des choix de l'internaute.
Ces événements sont déclenchés dès que
l'internaute enregistre ses choix, puis immédiatement sur les pages
suivantes.
Contrairement aux balises HTML et aux promesses, il n'est pas possible
d'utiliser d'astérisque (*
) pour les noms des
événements.
// Écouter un service en particulier
document.addEventListener('discreto-matomo', (event) => {
// event.detail contient le statut (booléen) pour ce service
let status = event.detail
console.info('matomo', status ? 'accepté' : 'refusé')
})
// Écouter tous les services
document.addEventListener('discreto', (event) => {
// event.detail contient le nom (name) et le statut (on) du service
let service = event.detail.name,
status = event.detail.on
console.info(service, status ? 'accepté' : 'refusé')
})
Attention : à partir du moment où l'internaute
a défini ses préférences, les événements seront déclenchés dès la fin
de chargement du DOM. Assurez-vous d'écouter suffisamment tôt, sinon
utilisez plutôt les promesses.
Promesses
Les promesses (Promise
) offrent plus de souplesse, et
permettent de vérifier qu'un service est activé ou d'en être informé
lorsqu'il le devient, et ce même après le chargement du DOM.
Si l'un des services est déjà activé, la promesse est immédiatement
résolue. Si aucun service n'est actif et que l'internaute a déjà
enregistré ses choix, la promesse est immédiatement rejetée. Sinon
la promesse est résolue ou rejetée à l'enregistrement des préférences.
discreto.when('youtube-api').then(() => {
// Résolu immédiatement (si le service est activé)
// ou dès l'accord de l'internaute
player.playVideo()
}, () => {
// Rejeté immédiatement (si le service est refusé)
// ou dès le refus de l'internaute
alert("Vous avez refusé le service YouTube :(")
})
Comme pour les balises HTML, on peut tirer parti du wildcard
pour autoriser un service ou ses variantes. Dans ce cas la promesse
est résolue avec le code du premier service accepté.
Exemple :
Pour attendre que l'internaute ait accepté Google Analytics
(analytics
) ou sa variante anonymisée
(analytics-anon
), on utilisera
discreto.when('analytics*')
:
button.addEventListener('click', (event) => {
// Analytics disponible ?
discreto.when('analytics*').then((service) => {
console.info('Le service', service, 'est actif')
gtag('event', 'click', button.getAttribute('data-click'))
}, () => {
// Il est toujours bon de traiter les promesses rejetées
})
})