Cookie-hozzájárulás Next.js‑hez, Gatsby‑hez és statikus oldalakhoz: integrációs útmutató fejlesztőknek
A statikus oldalak hozzájárulási problémája
A modern JavaScript‑keretrendszerek, mint a Next.js, Gatsby és Nuxt.js alapjaiban változtatták meg, hogyan épülnek és kerülnek kiszolgálásra a weboldalak. Az oldalak build időben vagy a szerveren előre renderelődnek, majd az ügyféloldalon hidratálódnak. Ez egyedi kihívást jelent a cookie‑hozzájárulás szempontjából: a hozzájárulási sávnak készen kell állnia, mielőtt bármilyen követőkód lefutna, miközben maga az oldal már renderelve és edge‑cache‑elve lehet.
A hagyományos CMP‑k olyan, szerveroldalon renderelt PHP‑ vagy egyszerű HTML‑oldalakhoz készültek, ahol a dokumentum felülről lefelé, lineárisan töltődik be. A keretrendszer‑világban azonban kódszeletelés, lazy loading és streaming server��side rendering működik, így ezek a feltételezések már nem állnak meg. Ahhoz, hogy ezekben a környezetekben helyesen kezeld a hozzájárulást, értened kell a renderelési folyamatot.
Miért számít a timing sokkal jobban, mint gondolnád
Egy hagyományos HTML‑oldalon egyszerűen a <head> részbe, a többi script elé teszed a CMP‑scriptet. Next.js App Router vagy Gatsby esetén a helyzet bonyolultabb:
- Előre renderelt HTML érkezik először: A böngésző teljes HTML‑t kap a CDN‑től vagy a szervertől. Ha ebben az HTML‑ben inline scriptek vagy harmadik féltől származó tagek vannak beágyazva, azok lefuthatnak, mielőtt a hozzájárulási logikád betöltődik.
- Hidratálási rés (hydration gap): A React‑hidratálás azután történik, hogy a HTML már megjelent. Ha a hozzájárulási felület egy React‑komponens, funkcionális állapotban csak a hidratálás után létezik. Ebben a résben a Google tagek vagy analitikai scriptek hozzájárulás nélkül is elsülhetnek.
- Edge‑cache komplikációk: Ha ISR‑t (Incremental Static Regeneration) vagy edge‑funkciókat használsz, a HTML cache‑elve van. Hozzájárulástól függő logikát nem tudsz dinamikusan beinjektálni a cache‑elt HTML‑be kliensoldali mechanizmus nélkül.
A lényegi elv ez: a hozzájárulást script‑szinten kell érvényesíteni, nem komponens‑szinten. Egy React‑komponens, amely a hozzájárulási sávot rendereli, már túl késő, ha csak a hidratálás után válik interaktívvá.
Next.js App Router integráció
A Next.js 13+ App Router új módot vezetett be a scriptek kezelésére. A hozzájárulás integrálásához ez az ajánlott megközelítés:
1. lépés: A CMP‑script betöltése a gyökér layoutban
Használd a Next.js Script komponensét beforeInteractive stratégiával a gyökér layout.tsx fájlban. Ezzel azt mondod a Next.js‑nek, hogy a scriptet az első HTML‑dokumentumba injektálja, még a hidratálás előtt:
A beforeInteractive stratégia kritikus. Az alapértelmezett afterInteractive stratégia a scripteket a hidratálás után tölti be, ami túl késő a hozzájáruláshoz. A beforeInteractive használatával a CMP‑script bekerül a szerveroldalon renderelt HTML‑be, és az oldal betöltésekor lefut.
2. lépés: Alapértelmezett hozzájárulás beállítása a Google tagek előtt
A Google Tag Manager vagy a gtag.js snippet előtt helyezz el egy inline scriptet, amely beállítja az alapértelmezett hozzájárulási állapotokat. Így még akkor is, ha a GTM a CMP‑sáv megjelenése előtt töltődik be, tiszteletben tartja az elutasító alapbeállításokat:
Ezt az inline scriptet a gyökér layout <head> részébe kell tenni, a CMP és a GTM scriptek elé. Next.js‑ben ehhez használhatsz egy hagyományos <script> taget a layout <head> elemén belül.
3. lépés: Útvonalváltások kezelése
Egy single‑page alkalmazás navigációja során a CMP‑script egyszer töltődik be, de az útvonalváltások nem okoznak teljes oldal‑újratöltést. A CMP‑nek kliensoldali navigációk között is fenn kell maradnia. A FlexyConsent ezt automatikusan kezeli — ha egyszer betöltődött, minden útvonalváltáson aktív marad újrainicializálás nélkül.
Next.js Pages Router integráció
Azoknál a projektnél, amelyek még a Pages Routert használják, a megközelítés hasonló, de a gyökér layout helyett a _document.tsx fájlt használja. A CMP‑scriptet a saját Document osztályod <Head> komponensébe helyezd. A beforeInteractive stratégia ugyanúgy működik a Pages Routerben is.
A fő különbség az, hogy a _document.tsx csak a szerveren renderelődik, így az itt lévő bármilyen hozzájárulási logika garantáltan benne lesz a kezdeti HTML‑válaszban.
Gatsby statikus oldal integráció
A Gatsby build időben teljesen statikus HTML‑t generál. Kérésidőben nincs szerveroldali renderelés, ami bizonyos szempontokat egyszerűsít, másokat viszont bonyolít:
- Használd a
gatsby-ssr.tsxfájlt a CMP‑script minden oldal<head>részébe injektálásához. AzonRenderBodyAPI lehetővé teszi, hogy olyan scripteket adj a head‑hez, amelyek minden statikus HTML‑fájlban jelen lesznek. - Kerüld azokat a Gatsby plugineket, amelyek lazy‑loadolják a hozzájárulást: Egyes közösségi pluginek a hozzájárulást olyan React‑komponensekbe csomagolják, amelyek csak a hidratálás után mountolódnak. Ez létrehozza a korábban említett timing rést.
- Helyezd el inline az alapértelmezett hozzájárulást: Használd a
setHeadComponentsfüggvényt agatsby-ssr.tsxfájlban, hogy egy inline scriptet adj hozzá, amely beállítja az alapértelmezett hozzájárulási állapotokat. Ez a script benne lesz a statikus HTML‑ben, és azonnal lefut.
A Gatsby build‑időben történő megközelítése azt jelenti, hogy a CDN‑eden lévő minden HTML‑fájl tartalmazni fogja a hozzájárulási scriptet. Ez valójában ideális — nincs olyan szerverlogika, ami hibázhatna vagy rosszul cache‑elődhetne.
Nuxt.js szempontok
A Nuxt.js (Vue‑alapú) saját mintákkal rendelkezik. Nuxt 3‑ban használd a useHead composable‑t vagy a nuxt.config.ts app head konfigurációját a CMP‑script globális hozzáadásához. A Nuxt támogatja a body: false opciót (ami a scripteket a head‑be helyezi), valamint az async attribútumot a nem blokkoló betöltéshez.
Nuxt szerveroldali renderelési módjában ugyanaz az elv érvényes: a CMP‑scriptnek a kezdeti HTML‑válaszban kell lennie, nem pedig egy Vue‑komponens által, mount után dinamikusan beinjektálva.
Layout shift elkerülése
A hozzájárulási sávok hírhedtek a Cumulative Layout Shift (CLS) okozásáról, ami egy Core Web Vital mutató, és hatással van az SEO‑rangsortokra. Amikor egy sáv az oldal renderelése után ugrik be, lenyomja a tartalmat vagy váratlanul ráfed.
Stratégiák a hozzájárulási sávokból eredő CLS minimalizálására:
- Használj alul elhelyezett sávot: A viewport alján lévő sávok nem tolják el az oldal tartalmát. Ez a leginkább CLS‑barát megoldás.
- Foglalj helyet előre: Ha mindenképp felső sávot használsz, foglald le a szükséges függőleges helyet a CSS‑ben, hogy az oldal layoutja már a renderelés előtt számoljon a sávval.
- Kerüld a betöltéskori modális overlayeket: A teljes képernyős hozzájárulási falak, amelyek az oldal renderelése után jelennek meg, érzékelhető layout‑instabilitást okoznak. Ha falra van szükséged, az legyen az oldal kezdeti állapotának része.
- Töltsd be a CMP‑t szinkron módon a head‑ben: Ha a CMP renderelést blokkoló scriptként töltődik be a head‑ben, a sáv az első festés részeként jelenhet meg, ahelyett, hogy később ugrana be.
A FlexyConsent keretrendszer‑független megközelítése
A FlexyConsentet úgy tervezték, hogy bármilyen keretrendszerrel — vagy akár keretrendszer nélkül — működjön, azáltal, hogy komponens‑szint helyett script‑szinten működik. Ennek ez az oka:
- Egyetlen aszinkron script tag: Egy
<script>tag a<head>részben elegendő. Nincs szükség npm csomagokra, keretrendszer‑specifikus wrappekre vagy build‑konfigurációra. - A hozzájárulási alapbeállítások azonnal lefutnak: A script első műveleteként beállítja a Consent Mode V2 alapértelmezéseket, bármilyen callback vagy DOM‑manipuláció előtt. Ez azt jelenti, hogy a Google tagek az első milliszekundumtól kezdve tiszteletben tartják a hozzájárulást.
- Nincs DOM‑függőség: A hozzájárulási logika nem vár a React, Vue vagy Svelte hidratálására. A keretrendszer életciklusától függetlenül működik.
- SSG‑vel, SSR‑rel, ISR‑rel és CSR‑rel is működik: Mivel egy egyszerű script, ugyanúgy funkcionál, függetlenül attól, hogy az oldal statikusan generált, szerveroldalon renderelt, inkrementálisan regenerált vagy kliensoldalon renderelt.
Fejlesztői tipp: A legegyszerűbb teszt a helyes CMP‑integrációra, ha megnyitod a böngésző Hálózat (Network) paneljét, Google domainekre szűrsz, majd újratöltöd az oldalt. Nem szabad Google kéréseknek lefutniuk, mielőtt a hozzájárulási alapértelmezett parancs megjelenik a konzolban. Ha mégis lefutnak, a CMP túl későn töltődik be.
A FlexyConsent ingyenes csomagja korlátlan pageview‑t támogat, és működik Next.js, Gatsby, Nuxt, Astro, SvelteKit, Remix és egyszerű HTML esetén is. Az integráció mindenhol ugyanaz: egyetlen script tag, megfelelő helyre téve.