dokumentacja · dla deweloperów

Instalacja snippetu

Jeden tag script umieszcza baner na stronie i wstrzymuje każdy nieniezbędny tracker do decyzji odwiedzającego. Są dwie zasady i to cała robota.

Tag

Skopiuj tag z Ustawienia strony → Instalacja w panelu. Zawiera klucz publiczny Twojej strony i środowisko, które ma ładować:

<script src="https://app.cookiecrumbs.eu/runtime/cc.js"
        data-cc-site="pk_live_…"
        data-cc-env="production"></script>

Każda strona ma dwa klucze: klucz produkcyjny dla prawdziwych odwiedzających i klucz preview, który ładuje to, co opublikowano na podgląd, żebyś mógł testować na stronie stagingowej, nie dotykając nikogo.

Zasada pierwsza: tag idzie na początek

Umieść tag jako pierwszy skrypt w <head>, przed każdym innym skryptem. Wszystko, co działa wcześniej, może ustawić cookie, gdy odwiedzający jeszcze decyduje, a runtime nie może tego cofnąć. Runtime instaluje interceptor synchronicznie, jeszcze przed pobraniem konfiguracji, więc nic nieniezbędnego nie uruchamia się, zanim istnieje wybór.

Zasada druga: skrypty wymagające zgody stają się nieaktywne

Skrypty wymagające zgody są oznaczane, żeby baner mógł je uwolnić, gdy ich kategoria zostanie przyznana:

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

Skrypt type="text/plain" sam z siebie nic nie robi. Gdy odwiedzający przyzna kategorię, runtime odtwarza skrypt w kolejności dokumentu i działa on normalnie. Skrypty inline działają tak samo: nadaj im type="text/plain" i data-cc-category.

Nieotagowane skrypty: lista blokowania

Nie musisz tagować wszystkiego. Trackery zapisane w panelu mają wzorce hostów, które przy publikacji są kompilowane do mapy blokowania. Każdy nieotagowany <script src> lub <iframe src>, którego host pasuje, jest neutralizowany na miejscu (skrypty stają się text/plain, iframe’y są wstrzymywane ze źródłem zaparkowanym w data-cc-src) i uwalniany, gdy jego kategoria zostanie przyznana. Zablokowane iframe’y pokazują tekst zastępczy, edytowalny per język w Baner → Teksty.

Systemy zarządzania treścią

WordPress: Wygląd → Edytor plików motywu → header.php, przed wp_head(), albo użyj pluginu do skryptów w nagłówku.
Shopify: Sklep online → Szablony → Edytuj kod → layout/theme.liquid, pierwsza linia w <head>.
Webflow: Ustawienia projektu → Custom code → Head code.

Zastrzeżenie dotyczące menedżerów tagów

Nie ładuj tagu CookieCrumbs przez menedżera tagów. Tag musi uruchomić się przed menedżerem; tag zgody odpalony z wnętrza menedżera działa za późno, by cokolwiek wstrzymać. Wklej go bezpośrednio do strony, nad menedżerem, i pozwól Consent Mode przenosić decyzje do Twoich tagów (zobacz przewodnik po Consent Mode).

Test instalacji

Test instalacji w panelu ładuje Twoją stronę w prawdziwej przeglądarce, akceptuje raz i raportuje, co faktycznie zobaczył. Nic nie jest brane na słowo. Sprawdza:

snippet jest obecny na stronie i umieszczony przed innymi tagami,
wartości domyślne Consent Mode są ustawione, zanim uruchomi się jakikolwiek tag Google,
baner został wyrenderowany, a klucz publiczny na stronie należy do tej strony,
po akceptacji zapisywane jest cookie zgody,
__tcfapi nie jest udostępniane: CookieCrumbs dziś nie implementuje IAB TCF.

Każdy nieudany test ma zdanie werdyktu wskazujące następny krok, na przykład: „Snippet jest, ale inne tagi działają przed nim. Przenieś tag nad każdy inny skrypt w head i uruchom test ponownie.” Prawdziwa decyzja zgody odwiedzającego również liczy się jako dowód, że instalacja działa.

Wolisz pakiet?

Jeśli Twoja strona jest zbudowana w Next.js, React, Astro, Nuxt lub SvelteKit, SDK dla frameworków umieszczają tag za Ciebie, a npx cookiecrumbs init wykrywa framework i zapisuje konfigurację.