Consentl dla każdej strony internetowej

Dodaj jeden tag script jako pierwszy w sekcji <head> witryny. Baner, teksty, regiony, Consent Mode i reguły blokowania konfiguruje się w panelu Consentl.

Skrypt ładujący jako pierwszy w <head>

Tak

Consentl działa w każdej witrynie, która pozwala dodać <script> do <head>. Na serwerze nie trzeba niczego instalować: wszystko konfiguruje się w panelu Consentl (zewnętrzna strona internetowa), a dostarcza to skrypt ładujący.

Co robi każdy plan

W planie Free tagi Google, Meta Pixel i wszystkie inne tagi uruchamiają się zaraz po załadowaniu strony, chyba że zostaną oznaczone ręcznie.

1. Dodanie witryny i skopiowanie klucza

1. Należy zalogować się do panelu (lub założyć bezpłatne konto) i dodać witrynę.
2. W polu Domeny witryny należy dodać każdą nazwę hosta, pod którą działa witryna. www. i domena bez www liczą się jako ta sama witryna; domeny testowe należy dodać osobno.
3. Należy otworzyć stronę Konfiguracja witryny i skopiować fragment kodu instalacyjnego. Zawarty w nim klucz witryny zaczyna się od sk_ i jest publiczny: identyfikuje witrynę, nie jest hasłem.

2. Instalacja skryptu ładującego

<script src="https://api.consentl.com/v1/loader.js?k=SITE_KEY&l=LANG"></script>

• SITE_KEY: klucz witryny (sk_ + 24 znaki).
• LANG: język strony, ta sama wartość co w <html lang>: en, de, fr, pt-PT, pt-BR, fr-CA, … Warianty regionalne są automatycznie sprowadzane do języka podstawowego (de-AT → de). Pominięcie &l= powoduje użycie domyślnego języka witryny z panelu.

Gdzie: jako pierwszy element w <head>, bezpośrednio po <meta charset>. Musi znajdować się przed Google Tag Manager, gtag.js, Meta Pixel, analityką, widżetami czatu i narzędziami do testów A/B.

Jak: synchronicznie: bez async, bez defer, bez type="module". Skrypt jest mały i przechowywany w pamięci podręcznej.

Dlaczego jako pierwszy i synchronicznie:

1. Wartości domyślne Google Consent Mode v2 (Pro i wyższe) muszą zostać ustawione, zanim odczyta je jakikolwiek tag Google.
2. Blokowanie powstrzymuje tagi przed uruchomieniem, dopóki odwiedzający nie wyrazi zgody. Skrypty znajdujące się powyżej skryptu ładującego już się uruchomiły.
3. Wybór powracającego odwiedzającego jest stosowany od razu: baner nie miga i żadne tagi nie uruchamiają się, zanim wybór nie jest znany.

Jeżeli Państwa platforma nie pozwala umieścić skryptu na pierwszym miejscu, jej poradnik dokładnie wyjaśnia, co to oznacza.

Co blokowanie może, a czego nie może powstrzymać

• Tagi ładowane przez kod (Google Tag Manager, skrypt ładujący JavaScript piksela, skrypty dodawane przez aplikację) są wstrzymywane przed ich pobraniem, gdy pasują do znanego narzędzia śledzącego (Business) lub do jednej z Państwa reguł blokowania.
• Tagi zapisane w kodzie HTML strony (<script src>, piksele <img>, <iframe>) są pobierane przez przeglądarkę, zanim jakikolwiek skrypt może je zatrzymać: podczas pobierania skryptu ładującego przeglądarka już pobiera to, co znajduje dalej na stronie. Consentl nadal uniemożliwia uruchomienie rozpoznanego skryptu, ale żądanie, z adresem IP odwiedzającego, adresem strony i ewentualnymi plikami cookie podmiotów trzecich, zostało już wysłane; w przypadku piksela śledzącego samo żądanie jest śledzeniem. Każdy tag zapisany w HTML należy oznaczyć ręcznie (sekcja 6), a piksele śledzące <noscript> usunąć.
• Witryny renderowane na serwerze mogą też wstawić skrypt ładujący inline, co eliminuje oczekiwanie na pobranie. Tagi zapisane w HTML nadal trzeba oznaczyć.

3. Sprawdzenie działania

1. Należy otworzyć witrynę w oknie prywatnym. Pojawia się baner.
2. W narzędziach deweloperskich przeglądarki → Console:
   • Consentl.get() zwraca bieżące wybory;
   • Consentl.region() zwraca model prawny zastosowany wobec odwiedzającego, np. { mode: "opt_in", law: "gdpr", gpc: false, known: true }.
3. W Network, przed akceptacją:
   • brak żądań do hostów śledzących z tagów ładowanych przez kod, gdy włączone jest automatyczne blokowanie (Business); przy Consent Mode tylko pingi Google bez plików cookie;
   • tagi zapisane w HTML, które nie zostały oznaczone, są pobierane. Należy je oznaczyć i sprawdzić ponownie.
4. Gdy witryna jest w trybie testowym, dodanie ?consentl=preview do adresu pozwala zobaczyć baner bez zapisywania i rejestrowania wyboru. Nie wybiera to regionu: Podgląd w panelu pokazuje baner dla każdego regionu.

Regiony: przy każdym wyświetleniu strony baner pyta Consentl o kraj odwiedzającego, ustalany na podstawie adresu IP odwiedzającego. Ustalenie odbywa się w pamięci i niczego nie zapisuje, a skrypt ładujący jest taki sam dla każdego odwiedzającego. Obowiązuje Państwa reguła dla danego kraju:

• Stany USA nie są rozróżniane: odwiedzający z USA otrzymuje Państwa regułę dla całych USA lub, jeżeli jej nie ma, pierwszą regułę dla stanu USA (na przykład Kalifornii).
• Gdy kraj jest nieznany, obowiązuje reguła dla nieznanych regionów (domyślnie opt-in).
• Kod znajduje się w polu dataLayer consentl.region (na przykład DE lub US). Aby zobaczyć baner innego regionu, należy użyć Podglądu w panelu lub VPN.

4. Dodanie linku „Ustawienia plików cookie”

Wycofanie zgody musi być równie łatwe jak jej wyrażenie. Można użyć dowolnego z poniższych:

<a href="#consentl">Cookie settings</a>
<button type="button" data-consentl-open>Cookie settings</button>

window.Consentl.open("prefs");

Linki, których adres kończy się na #consentl lub #consentl-preferences, oraz każdy element z data-consentl-open otwierają preferencje zamiast przechodzić do innej strony, również w przypadku elementów dodanych później. Inne kotwice, które tylko zaczynają się tak samo (np. #consentl-api), pozostają bez zmian. Panel może też wyświetlać pływającą ikonę preferencji.

5. Deklaracja plików cookie, wnioski dotyczące danych osobowych i unijny formularz odstąpienia od umowy

<div data-consentl-declaration data-api="https://api.consentl.com" data-key="SITE_KEY" data-locale="LANG"></div>
<div data-consentl-request      data-api="https://api.consentl.com" data-key="SITE_KEY" data-locale="LANG"></div>
<div data-consentl-withdrawal   data-api="https://api.consentl.com" data-key="SITE_KEY" data-locale="LANG"></div>
<script src="https://api.consentl.com/v1/blocks.js" defer></script>

blocks.js należy dołączyć raz na stronę, po elementach <div>. Deklaracja zawiera listę plików cookie ze strony Pliki cookie w panelu: skaner dodaje to, co znajdzie, podczas tworzenia witryny, po kliknięciu Skanuj teraz oraz, w planie Business i wyższych, co miesiąc; wpisy można też dodawać lub edytować samodzielnie (szczegóły są uzupełniane z Open Cookie Database). Wnioski dotyczące danych osobowych są weryfikowane e-mailem i pojawiają się w panelu wraz z terminem. Unijny formularz odstąpienia od umowy wymaga planu Pro lub wyższego i musi zostać włączony w panelu; w przeciwnym razie jego <div> pozostaje pusty.

6. Wstrzymywanie wszystkiego, co nie jest rozpoznawane automatycznie

<script type="text/plain" data-consentl="marketing" src="https://ads.example.com/tag.js"></script>
<script type="text/plain" data-consentl="analytics">/* inline code */</script>
<iframe data-consentl="marketing" data-src="https://www.youtube-nocookie.com/embed/ID" title="Video"></iframe>
<img data-consentl="marketing" data-src="https://tracker.example.com/pixel.gif" alt="" width="1" height="1">

• Kategorie: preferences, analytics, marketing.
• Nic nie jest pobierane, dopóki nie zostanie udzielona zgoda na daną kategorię. To jedyny sposób na wstrzymanie tagu zapisanego w HTML.
• Do oznaczonego skryptu, który musi działać jako moduł, należy dodać data-consentl-type="module".
• Ręczne blokowanie działa w każdym planie. Plan Business dodaje automatyczne blokowanie znanych narzędzi śledzących i reguły blokowania („URL contains”) dodawane w panelu bez ingerencji w witrynę. Reguły są dopasowywane do adresu skryptów, elementów iframe i obrazów oraz do skryptów inline, które coś ładują. Dane strony frameworków takich jak Next.js, Nuxt, Remix czy SvelteKit nigdy nie są wstrzymywane.
• Wstrzymany tag uruchamia się raz po wyrażeniu zgody, nawet jeżeli framework dodaje jego drugą kopię podczas uruchamiania strony (tak robi Nuxt).

Aplikacje jednostronicowe

• Przy zmianach trasy nie trzeba niczego wywoływać: środowisko uruchomieniowe jest ładowane raz na dokument, wybór jest przechowywany we własnym pliku cookie consentl, a wstrzymane tagi są zwalniane bez przeładowania.
• Routery, które podmieniają treść strony (Astro <ClientRouter />, Turbo, Swup, htmx hx-boost), zachowują działanie banera, pływającej ikony i linków „Ustawienia plików cookie”.
• Adres skryptu ładującego powinien być taki sam na każdej stronie i nie należy ładować go ponownie przy nawigacji. Jeżeli kreator oferuje „load on every page”, należy wybrać „load once”.
• Tagi wstawiane później przez aplikację również są wstrzymywane, gdy pasują do znanego narzędzia śledzącego (Business) lub reguły blokowania. We własnym kodzie należy sprawdzać zgodę. Zdarzenie consentl:change jest wywoływane przy każdym wyświetleniu strony z bieżącymi wyborami i ponownie przy każdej zmianie, dlatego należy uruchamiać funkcje tylko raz:

let started = false;
const maybeStart = (c) => {
  if (c.analytics && !started) {
    started = true;
    startAnalytics();
  }
};
document.addEventListener("consentl:change", (e) => maybeStart(e.detail));
if (window.Consentl) maybeStart(window.Consentl.get());

• Po zmianie języka bez pełnego przeładowania baner zachowuje swój język do następnego załadowania strony.

Z Google Tag Manager

Szablon Consentl GTM może zarządzać Google Consent Mode. Jeżeli używają Państwo go razem z fragmentem kodu, należy dodać &gcm=ext do adresu skryptu ładującego, aby polecenia Consent Mode wysyłał tylko szablon:

<script src="https://api.consentl.com/v1/loader.js?k=SITE_KEY&l=LANG&gcm=ext"></script>

Wstawianie inline (po stronie serwera)

Jeżeli Państwa strony są renderowane na serwerze, nad którym mają Państwo kontrolę, można wstawić skrypt ładujący bezpośrednio w kod strony zamiast go linkować, tak jak robią to wtyczki Consentl dla WordPress, Shopware, PrestaShop i Magento:

1. Na serwerze należy pobrać https://api.consentl.com/v1/loader.js?k=SITE_KEY&l=LANG.
2. Odpowiedź należy przechowywać w pamięci podręcznej dla każdego klucza witryny i języka przez 5 minut (zgodnie z jej Cache-Control); jeżeli późniejsze pobranie się nie powiedzie, należy nadal udostępniać ostatnią poprawną kopię.
3. Należy wstawić <script> + odpowiedź + </script> jako pierwszy element w <head>. Przy Content Security Policy należy dodać nonce (treść zmienia się wraz z ustawieniami, więc skrót nie zadziała).
4. Jeżeli w ogóle nie ma kopii w pamięci podręcznej, należy wstawić zwykły tag <script src="…">.

// Node, simplified
const cache = new Map(); // url -> { body, until }
async function consentlHead(key, lang) {
  const url = `https://api.consentl.com/v1/loader.js?k=${encodeURIComponent(key)}&l=${encodeURIComponent(lang)}`;
  const hit = cache.get(url);
  if (!hit || hit.until < Date.now()) {
    try {
      const r = await fetch(url);
      if (r.ok) cache.set(url, { body: await r.text(), until: Date.now() + 300_000 });
    } catch {
      /* keep the stale copy */
    }
  }
  const body = cache.get(url)?.body;
  return body ? `<script>${body}</script>` : `<script src="${url}"></script>`;
}

Nie należy zmieniać odpowiedzi: jest generowana przez Consentl dla Państwa witryny. Należy wstawiać ją w szablonie HTML zapisywanym przez serwer, poza jakimkolwiek frameworkiem po stronie klienta. Nie dotyczy to Next.js App Router: React wysyłałby tam skrypt ładujący dwukrotnie na każdej stronie; należy użyć zwykłego tagu, jak pokazano w poradniku Next.js.

Interfejs API JavaScript

Zdarzenia na document (wybory znajdują się w event.detail):

• consentl:change: przy każdym wyświetleniu strony po zastosowaniu reguły regionu i przy każdej zmianie;
• consentl:ready: raz na wyświetlenie strony, po pierwszym consentl:change;
• consentl:ui-error: nie udało się załadować banera (również po jednej ponownej próbie). Linki do #consentl działają wtedy jak zwykłe linki, więc można wyświetlić własne rozwiązanie zastępcze.

dataLayer otrzymuje consentl_consent (przy każdym wyświetleniu strony i każdej zmianie) i consentl_update (tylko przy zmianach), każde z consentl.preferences, analytics, marketing, sale, stored i region. Oznaczone elementy: data-consentl="<category>", type="text/plain", data-src, data-consentl-srcset (obrazy z srcset), data-consentl-type. Na stronach, które mają własny przycisk „Ustawienia plików cookie”, można dodać data-consentl-noicon do elementu, aby ukryć tam pływającą ikonę.

Content Security Policy

Jeżeli witryna wysyła nagłówek Content-Security-Policy, należy zezwolić na API Consentl:

script-src  'self' https://api.consentl.com;
connect-src 'self' https://api.consentl.com;
img-src     'self' https://api.consentl.com data:;
style-src   'self' 'unsafe-inline';

• style-src 'unsafe-inline' jest potrzebne, ponieważ baner dodaje swoje style w czasie działania. Jeżeli Państwa polityka zabrania stylów inline, prosimy o kontakt z pomocą techniczną.
• Skrypty zwalniane przez Consentl po wyrażeniu zgody nadal potrzebują własnych hostów w script-src.
• Przy ścisłej polityce opartej na nonce należy nadać nonce tagowi skryptu ładującego i użyć 'strict-dynamic', aby skrypty, które ładuje i zwalnia, były zaufane. Bez 'strict-dynamic' nonce należy nadać także oznaczonym skryptom inline.
• Subresource Integrity (SRI) nie może być używane dla skryptu ładującego, ponieważ jego treść zmienia się przy zmianie ustawień w panelu.

Kontrole po stronie serwera (opcjonalnie)

Wybór jest przechowywany we własnym pliku cookie consentl: 1.<id>.<timestamp>.<revision>.<flags>.<action>. flags ma cztery cyfry dla preferences, analytics, marketing i sale (1 = zgoda udzielona). Brak pliku cookie oznacza brak decyzji: należy traktować to jako „brak zgody”. Plik cookie ze starszą wersją (po „Reset all consents”) przestaje się liczyć. Strony zależne od tego pliku cookie nie mogą być przechowywane we współdzielonej pamięci podręcznej. W miarę możliwości lepiej stosować warunkowanie po stronie klienta (sekcja 6).

Ograniczenia

• Baner nie może kontrolować skryptów uruchamianych przed skryptem ładującym: skryptów powyżej niego w <head> oraz skryptów, które platforma hostingowa wstrzykuje poza Państwa kontrolą.
• Tagi zapisane w kodzie HTML strony są pobierane przed wyrażeniem zgody, chyba że zostaną oznaczone.
• Osadzone elementy iframe podmiotów trzecich (filmy, mapy) są wstrzymywane w całości do czasu wyrażenia zgody. Consentl nie widzi, co dzieje się w ich wnętrzu.
• Consentl nie implementuje IAB Transparency & Consent Framework (TCF).

Powiązane poradniki

• Google Tag Manager
• Next.js
• React, Vue, Angular (SPA)
• Webflow

Potrzebują Państwo pomocy? Prosimy pisać na adres support@consentl.com — odpowiadamy po angielsku w dni robocze.