Menu dokumentacji

Global Privacy Control

Sygnały prywatności w CookieHug: Global Privacy Control (GPC), DNT i adapter US Privacy (USP) — tryby, nadpisanie przez użytkownika, toaster i zdarzenia.

Global Privacy Control (Sprint 1)

CookieHug wykrywa navigator.globalPrivacyControl === true na każdej stronie i reaguje zgodnie z bannerConfig.gpc.mode.

Tryby GPC

Tryb	Zachowanie
`auto_deny_toaster` (rekomendowane)	Automatycznie odrzuca wszystkie kategorie nieesencjalne, ukrywa baner, pokazuje toaster z możliwością nadpisania.
`auto_deny_silent`	Auto-deny bez toastera.
`preselect_off_banner`	Baner pokazany z wyłączonymi togglami nieesencjalnymi.
`ignore`	GPC tylko logowane do analityki, nie wpływa na zgodę.

Nadpisanie przez użytkownika

Gdy gpc.allowUserOverride jest true (domyślnie), toaster zawiera przycisk "Dostosuj" otwierający pełny baner. Wybrany stan jest zapisany jako method="gpc_override".

Wygląd toastera

bannerConfig.gpc.visual kontroluje toaster (variant/pozycja/kolory/ikona/animacja/przyciski/zachowanie). Toaster renderuje się w Shadow DOM (izolacja stylów) i respektuje prefers-reduced-motion.

Eventy

Event	Detail
`CookieHugOnGpcDetected`	`{ mode, autoDenied, userOverrideAvailable }`
`CookieHugOnGpcToasterShown`	`{ mode }`
`CookieHugOnGpcToasterDismissed`	`{ reason: 'user' \\| 'auto' }`
`CookieHugOnGpcOverrideRequested`	`{}` — emitowany przed re-otwarciem banera. Flaga sesyjna sprawia, że kolejne `setConsent` zostanie zapisane jako `method="gpc_override"`.
`CookieHugOnDntDetected`	`{ autoDenied: false, userOverrideAvailable: true }` — emitowany gdy `respectDnt=true` i przeglądarka wysyła `DNT: 1` (a GPC nie miał wcześniej pierwszeństwa).

Do Not Track

Gdy respectDnt jest włączone i navigator.doNotTrack === '1', policy engine wymusza miękki preselect-off: banner pokazuje się normalnie, ale wszystkie niewymagane checkboxy startują odznaczone. Użytkownik nadal może świadomie udzielić zgody. GPC zawsze ma pierwszeństwo przed DNT (precedencja: GPC > DNT > normal flow). Wyłączenie respectDnt zostawia doNotTrack jako sygnał wyłącznie telemetryczny w event payloadach i cookie zgody.

Czego CookieHug NIE robi

Nie modyfikuje API Privacy Sandbox. accounts.google.com/gsi/, FedCM, Topics API, Attribution Reporting i Private State Tokens są na liście dozwolonych skryptów.
Nie przechowuje IP ani geolokalizacji odwiedzającego; region jest rozwiązywany przejściowo per request.

Cookie zgody v2

Gdy decyzja jest nietrywialna, CookieHugConsent rozszerza się do v2:

{
  "v": 2,
  "necessary": true,
  "preferences": true,
  "statistics": true,
  "marketing": false,
  "stamp": 1712345678901,
  "method": "gpc_auto_deny",
  "region": "US-CA",
  "signals": {
    "ad_storage": "denied",
    "ad_user_data": "denied",
    "ad_personalization": "denied",
    "analytics_storage": "granted"
  }
}

Czytnik wstecznie kompatybilny z v1 (brakujące pola = defaulty). method rozszerzone o: explicit, gpc_auto_deny, gpc_override, migrated_v1, notice_only.

Adapter US Privacy (USP / CCPA)

Opcjonalny (włączany per domena) adapter US Privacy API v1 IAB — włączysz go w Domena → Zaawansowane → Polityka zgody → US Privacy (USP). Po włączeniu SDK rejestruje window.__uspapi (tylko jeśli strona nie udostępnia już własnego), dzięki czemu partnerzy reklamowi mogą odczytać „usp string” CCPA/CPRA:

window.__uspapi('getUSPData', 1, function (data, success) {
  // data.uspString — np. "1YNN"
});

String powstaje z decyzji odwiedzającego w banerze: pozycja 2 (notice) zmienia się na Y, gdy odwiedzający odpowiedział na baner, pozycja 3 (opt-out ze sprzedaży) to Y przy odrzuconej kategorii Marketing i N przy zaakceptowanej, a pozycja 4 (LSPA) to zawsze N. Przed jakąkolwiek decyzją adapter zwraca 1N-N. Po każdej decyzji (akceptacja, odmowa, wycofanie, przywrócenie przy powrocie) na window emitowany jest CustomEvent uspChange z detail.uspString.