Dokumentacja / Instalacja skryptu

Instalacja skryptu Cookienovo

Informacje techniczne o banerze Cookienovo dla programistów: jak wstawić skrypt, konfigurować tagi, blokować skrypty według kategorii i podłączyć Google Consent Mode v2.

Wstawianie skryptu

Aby Twoja witryna wyświetlała baner Cookienovo i zbierała zgody na pliki cookie, wstaw nasz skrypt do kodu źródłowego strony. Znajdziesz go na swoim koncie Cookienovo (otrzymałeś go również e-mailem przy rejestracji). Skrypt wstaw do sekcji <head>, jak najwyżej — przed Google Tag Manager i pozostałe skrypty pomiarowe.

Instalacja składa się z dwóch części: (1) skrypt inline, który synchronicznie ustawia domyślne zgody Google Consent Mode v2 przed uruchomieniem jakichkolwiek tagów Google, oraz (2) sam skrypt banera:

<!-- Krok 1: domyślne zgody PRZED jakimikolwiek tagami Google -->
<script>
window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments);}
gtag('consent','default',{'ad_storage':'denied','ad_personalization':'denied','ad_user_data':'denied','analytics_storage':'denied','functionality_storage':'denied','personalization_storage':'denied','security_storage':'granted','wait_for_update':500});
gtag('set','ads_data_redaction',true);
</script>
<!-- Krok 2: baner Cookienovo (można użyć defer) -->
<script site-token="<site-token>" type="text/javascript" src="https://cookienovo.com/assets/client.js" defer></script>

Używasz wtyczki optymalizacyjnej lub cache (WP Rocket, LiteSpeed Cache, Autoptimize, SG Optimizer, W3 Total Cache…)? Wyklucz skrypt Cookienovo z jej modyfikacji — zwłaszcza z minifikacji/łączenia JavaScriptu i z opóźnionego uruchamiania (Delay JavaScript). Do list wyjątków dodaj cookienovo a po zmianie wyczyść cache wtyczki. W przeciwnym razie baner cookie może się nie wyświetlić.

Tagi skryptu

Skrypt banera Cookienovo obsługuje następujące atrybuty:

site-token — wymagane. UUID Twojej strony z konta Cookienovo (otrzymałeś je również e-mailem). Bez poprawnego tokenu baner się nie wyświetli. Token je nezávislý od URL a schémy webu — pri prechode z http:// na https:// (alebo inej zmene URL webu v účte) ostáva rovnaký, takže netreba re-inštaláciu ani výmenu snippetu.
theme — opcjonalne. Wymusza motyw banera: "light" lub "dark".
consent-mode — opcjonalne. Nadpisuje tryb zgody banera. Domyślnie "true"; ustaw "false", jeśli nie chcesz wysyłać zgód.

Blokowanie skryptów według kategorii

Aby skrypty pomiarowe i marketingowe uruchamiały się dopiero po wyrażeniu zgody, przypisz im kategorię za pomocą atrybutu cn-category. Baner Cookienovo uruchomi je dopiero wtedy, gdy odwiedzający zezwoli na daną kategorię:

<script type="text/javascript" cn-category="analytics">
  // skrypt analityczny
</script>

Możliwe wartości atrybutu cn-category: necessary (niezbędne), functional (funkcjonalne), analytics (analityka), marketing.

Przetwarzanie zdarzeń

Jeśli chcesz przetwarzać stan zgody we własnych skryptach, nasłuchuj zdarzenia CookienovoUserConsentChanged:

<script type="text/javascript">
  document.addEventListener("CookienovoUserConsentChanged", (e) => {
    console.log("zgoda zmieniona", e.detail);
  });
</script>

W obiekcie detail znajdziesz stan zgody dla każdej kategorii (kategoria + wartość logiczna, czy użytkownik ją włączył):

{
  "detail": [
    { "category": "necessary",  "allowed": true  },
    { "category": "analytics",  "allowed": false },
    { "category": "functional", "allowed": true  },
    { "category": "marketing",  "allowed": true  }
  ]
}

Google Consent Mode v2

Cookienovo w pełni spełnia wymogi Google Consent Mode v2 i konfiguruje go automatycznie — bez ingerencji użytkownika czy administratora. Domyślne zgody ustawiane są od razu przy ładowaniu strony i aktualizowane po wyborze odwiedzającego.

Dzięki dwuczęściowej instalacji (domyślne zgody inline + skrypt banera) sygnały ad_storage, analytics_storage, ad_user_data i ad_personalization domyślnie ustawione na 'denied' jeszcze przed uruchomieniem tagów Google. Podejście jest zgodne ze standardami branżowymi i działa również z asynchronicznie ładowanymi tagami Google. Ustawienia domyślne obejmują wait_for_update:500 i ads_data_redaction:true dla maksymalnej ochrony prywatności.

Więcej w dokumentacji Google.

Funkcje debugowania

Do weryfikacji implementacji Consent Mode v2 Cookienovo udostępnia funkcje debugowania, które uruchomisz w konsoli przeglądarki. Otwórz konsolę (F12) na dowolnej stronie z zainstalowanym Cookienovo i uruchom:

// włącz tryb debug i uruchom pełną walidację
window.cookienovoDebug.enableDebugMode()

// tylko kontrole walidacyjne
window.cookienovoDebug.runFullValidation()

// raport zgodności
window.cookienovoDebug.generateComplianceReport()

// stan Consent Mode
window.cookienovoDebug.checkConsentMode()

// test implementacji
window.cookienovoDebug.testConsentModeImplementation()

// sprawdzenie integracji z Shopify
window.cookienovoDebug.checkShopifyIntegration()

Funkcje wypiszą szczegółowe informacje o Twojej implementacji: wynik zgodności, wykryte tagi Google, problemy i konkretne rekomendacje. Diagnostykę możesz uruchomić również z pulpitu bez otwierania konsoli.

Automatyczne blokowanie trackerów

Cookienovo potrafi automatycznie neutralizować trackery firm trzecich spoza Google (na przykład Facebook Pixel, Hotjar czy Microsoft Clarity) przed udzieleniem zgody i ponownie je aktywować w momencie, gdy odwiedzający zezwoli na odpowiednią kategorię. Tagi Google są obsługiwane osobno przez Consent Mode v2, więc nie trzeba ich blokować ręcznie.

Przy obsługiwanych trackerach nie są potrzebne żadne zmiany w kodzie. Blokowanie działa w miarę możliwości (best-effort): obejmuje listę znanych trackerów i skrypty umieszczone bezpośrednio w <head> mogą raz uruchomić się, zanim blokada zadziała. Aby mieć pewność zablokowania dowolnego skryptu, oznacz go ręcznie zgodnie z instrukcją powyżej. Automatyczne blokowanie włączysz lub wyłączysz samodzielnie w ustawieniach banera swojej witryny — przełącznik „Automatyczne blokowanie trackerów”. Przy nowych witrynach jest domyślnie włączone.

Content Security Policy (CSP)

Ak na svojom webe používate Content Security Policy, banner Cookienovo funguje bez toho, aby ste museli povoliť externé zdroje. Lišta neťahá žiadny externý stylesheet ani webfont — CSS vkladá inline priamo na stránku a používa systémové písmo (system-ui). Direktívy font-src ani externý style-host preto netreba. Stačí povoliť tieto direktívy:

script-src — host, ktorý servíruje client.js (napríklad cookienovo.com).
connect-src — API origin, kam banner posiela požiadavky (cookienovo.com): konfigurácia /api/config a consent endpointy (/consents, /consents/event).
img-src 'self' data: <logo-host> — data: pre vstavanú ikonu a maskota (vložené priamo v skripte ako data: URI) a host externej URL, ak používate vlastné logo z inej domény.
style-src 'unsafe-inline' — lišta injektuje na stránku vlastný blok <style> a používa inline atribúty style.

Prečo tie dve uvoľnenia: ikony a maskot sú v skripte zapečené ako data: URI (žiadny externý obrázok), preto v img-src stačí pridať data:. Štýly banneru sa vkladajú cez injektovaný <style> blok a inline style atribúty, čo vyžaduje 'unsafe-inline' v style-src.

Link w stopce: ponowne otwarcie ustawień cookies

Domyślnie mały pływający przycisk „Cookies” umożliwia odwiedzającym ponowne otwarcie ich preferencji. Jeśli chcesz go ukryć (ustaw ikonę na Ukryte w ustawieniach banera) i otwierać preference center z własnego linku — na przykład „Ustawienia cookies” w stopce — dodaj do dowolnego elementu atrybut data-cookienovo-settings:

<a href="#" data-cookienovo-settings>Ustawienia cookies</a>

Albo otwórz go programowo z własnego JavaScriptu:

window.cookienovo.showConsentSettings()