updated docs

2026-08-04 19:37:23 +02:00
parent 9a45b3a50f
commit 90cbc4370f
19 changed files with 290 additions and 272 deletions
@@ -0,0 +1,75 @@
+# analytics
+
+Ładuje GA4 albo Google Tag Manager, spięte z modułem consent: Consent Mode
+dostaje decyzję odwiedzającego, zanim tag się załaduje, i aktualizację w
+momencie kliknięcia w banerze.
+
+## Config
+
+Brak opcji w `payload.config` — plugin czyta ID z globala **Site Integrations**
+(Settings → Site Integrations):
+
+- **GA4 Measurement ID** — `G-XXXXXXXXXX`
+- **GTM Container ID** — `GTM-XXXXXXX`
+
+Gdy ustawione są oba, wygrywa GTM. Gdy żadne — komponent nie robi nic.
+
+To jedyne pola z Site Integrations, które trafiają na klienta — są publiczne
+(widać je w źródle każdej strony z GA). `getAnalyticsConfig` czyta wyłącznie je,
+więc sekrety (Turnstile, SMTP) nie mają jak wyciec.
+
+## Front
+
+W layoucie locale, **wewnątrz `ConsentProvider`**:
+
+```tsx
+import { getAnalyticsConfig } from '@intecion/ipal-kit'
+import { ConsentProvider, CookieBanner, Analytics } from '@intecion/ipal-kit/client'
+
+export default async function LocaleLayout({ children, params }) {
+  const payload = await getPayload({ config })
+  const analytics = await getAnalyticsConfig(payload)   // server
+
+  return (
+    <ConsentProvider texts={texts}>
+      {children}
+      <CookieBanner />
+      <Analytics {...analytics} />
+    </ConsentProvider>
+  )
+}
+```
+
+`Analytics` nie renderuje nic — wstrzykuje skrypty. Zamontuj raz, wysoko w
+drzewie.
+
+## Jak działa Consent Mode
+
+1. Przed załadowaniem tagu: `gtag('consent', 'default', …)` z zapisaną decyzją
+   odwiedzającego (albo wszystko `denied`, gdy jeszcze nie zdecydował).
+2. Tag się ładuje i respektuje ten stan od pierwszego trafienia.
+3. Klik w banerze → `gtag('consent', 'update', …)` → tagi reagują natychmiast.
+
+Mapowanie kategorii na sygnały Google:
+
+| Kategoria | Sygnały |
+|---|---|
+| analytics | `analytics_storage` |
+| marketing | `ad_storage`, `ad_user_data`, `ad_personalization` |
+| functional | `functionality_storage`, `personalization_storage` |
+| necessary | `security_storage` (zawsze `granted`) |
+
+## Testowanie
+
+W konsoli: `window.dataLayer` — powinien zawierać `Arguments(3)` z `consent` /
+`default`, a po decyzji `consent` / `update`. Jeśli widzisz `Array` zamiast
+`Arguments`, komenda nie zostanie rozpoznana przez Google.
+
+Ciasteczko `_ga` pojawia się dopiero po zgodzie na analytics — to jest sedno
+Consent Mode.
+
+**GTM sam nie ustawia ciasteczek** — to pojemnik. Bez opublikowanego (Submit →
+Publish, nie sam zapis) tagu GA4 w kontenerze wszystko wygląda dobrze:
+`gtm.load` w dataLayer, Tag Assistant widzi kontener — a `_ga` nie ma, bo nic go
+nie tworzy. Przy debugowaniu warto tymczasowo wyczyścić GTM Container ID i
+zostawić samo GA4, żeby wyeliminować kontener jako zmienną.