Vadnica1. junij 2026 | FlexyConsent

Soglasje za piškotke v Next.js, Gatsby in statičnih straneh: integracijski vodnik za razvijalce

Težava soglasja pri statičnih straneh

Sodobna JavaScript ogrodja, kot so Next.js, Gatsby in Nuxt.js, so uvedla spremembo paradigme v tem, kako so spletne strani zgrajene in dostavljene. Strani so predizrisane v času gradnje ali na strežniku, nato pa na odjemalcu hidrirane. To ustvarja edinstven izziv za soglasje za piškotke: pasica za soglasje mora biti pripravljena, še preden se izvedejo kakršni koli sledilni skripti, vendar je lahko sama stran že izrisana in predpomnjena na robu (edge).

Tradicionalni CMP-ji so bili zasnovani za strežniško izrisane PHP ali preproste HTML strani, kjer se dokument nalaga linearno od vrha navzdol. V svetu ogrodij z razbitjem kode (code splitting), lenim nalaganjem (lazy loading) in pretočnim strežniškim izrisom (streaming server-side rendering) te predpostavke odpovejo. Pravilno upravljanje soglasja v takih okoljih zahteva razumevanje upodabljalnega cevovoda (rendering pipeline).

Zakaj je časovna usklajenost pomembnejša, kot si mislite

V standardni HTML strani je postavitev CMP skripta v <head> pred druge skripte preprosta. V Next.js App Router ali Gatsby je situacija bolj zapletena:

Najprej prispe predizrisan HTML: Brskalnik prejme celoten HTML iz CDN ali strežnika. Če so v ta HTML vgrajeni kakršni koli inline skripti ali zunanje oznake tretjih oseb, se lahko izvedejo, še preden se naloži vaša logika soglasja.
Vrzel hidracije: Hidracija v Reactu se zgodi po tem, ko je HTML že izrisan. Če je vaš element za soglasje React komponenta, v funkcionalnem stanju ne obstaja, dokler se hidracija ne zaključi. V tej vrzeli se lahko Google oznake ali analitični skripti sprožijo brez soglasja.
Zapleti zaradi robnega predpomnjenja: Če uporabljate ISR (Incremental Static Regeneration) ali edge funkcije, je HTML predpomnjen. V predpomnjeni HTML ne morete dinamično vbrizgati logike, ki je odvisna od soglasja, brez mehanizma na strani odjemalca.

Osnovno načelo je naslednje: soglasje mora biti vzpostavljeno na ravni skriptov, ne na ravni komponent. React komponenta, ki izriše pasico za soglasje, je prepozna, če postane interaktivna šele po hidraciji.

Integracija z Next.js App Router

Next.js 13+ z App Router je uvedel nov način ravnanja s skripti. Tukaj je priporočeni pristop za integracijo soglasja:

Korak 1: Naložite CMP skript v korenski postavitvi (root layout)

Uporabite Next.js komponento Script s strategijo beforeInteractive v vašem korenskem layout.tsx. S tem Next.jsu poveste, naj skript vbrizga v začetni HTML dokument, še preden se začne hidracija:

Strategija beforeInteractive je ključna. Privzeta strategija afterInteractive nalaga skripte po hidraciji, kar je za soglasje prepozno. Z beforeInteractive je CMP skript vključen v strežniško izrisan HTML in se izvede med nalaganjem strani.

Korak 2: Nastavite privzeto soglasje pred Google oznakami

Pred vašim Google Tag Manager ali gtag.js odrezkom vključite inline skript, ki nastavi privzeta stanja soglasja. To zagotovi, da tudi če se GTM naloži, preden se pojavi CMP pasica, spoštuje privzete zavrnitve:

Ta inline skript mora biti postavljen v <head> vaše korenske postavitve, pred CMP in GTM skripti. V Next.js lahko za ta namen uporabite običajno oznako <script> znotraj elementa <head> v vaši postavitvi.

Korak 3: Obdelajte spremembe poti (route changes)

Pri enostranskem načinu navigacije (SPA) se CMP skript naloži enkrat, spremembe poti pa ne sprožijo celotnega ponovnega nalaganja strani. Vaš CMP mora vztrajati skozi navigacije na strani odjemalca. FlexyConsent to obravnava samodejno — ko je enkrat naložen, ostane aktiven skozi vse spremembe poti brez ponovne inicializacije.

Integracija z Next.js Pages Router

Za projekte, ki še vedno uporabljajo Pages Router, je pristop podoben, vendar uporablja _document.tsx namesto korenske postavitve. CMP skript postavite v komponento <Head> vaše prilagojene Document klase. Strategija beforeInteractive deluje enako tudi v Pages Router.

Ključna razlika je, da se _document.tsx izrisuje samo na strežniku, zato je vsa logika soglasja tukaj zagotovljeno vključena v začetni HTML odziv.

Integracija statičnih strani v Gatsby

Gatsby v času gradnje generira popolnoma statičen HTML. V času zahteve ni strežniškega izrisa, kar nekatere vidike poenostavi, druge pa zaplete:

Uporabite gatsby-ssr.tsx za vbrizg CMP skripta v <head> vsake strani. API onRenderBody vam omogoča dodajanje skriptov v head, ki bodo prisotni v vsaki statični HTML datoteki.
Izogibajte se Gatsby vtičnikom, ki leno nalagajo soglasje: Nekateri skupnostni vtičniki zavijejo soglasje v React komponente, ki se namestijo šele po hidraciji. To ustvari časovno vrzel, opisano prej.
Privzeta soglasja postavite inline: Uporabite setHeadComponents v gatsby-ssr.tsx za dodajanje inline skripta, ki nastavi privzeta stanja soglasja. Ta skript bo v statičnem HTML in se bo izvedel takoj.

Gatsbyjev pristop v času gradnje pomeni, da bo vsaka HTML datoteka na vašem CDN vsebovala skript za soglasje. To je pravzaprav idealno — ni strežniške logike, ki bi lahko spodletela ali bila napačno predpomnjena.

Posebnosti Nuxt.js

Nuxt.js (na osnovi Vue) ima svoje vzorce. V Nuxt 3 uporabite composable useHead ali konfiguracijo glave aplikacije v nuxt.config.ts, da globalno dodate CMP skript. Nuxt podpira možnost body: false (ki postavi skripte v head) in atribut async za neblokirajoče nalaganje.

Za strežniško izrisni način Nuxt velja isto načelo: CMP skript mora biti v začetnem HTML odzivu, ne pa dinamično vbrizgan z Vue komponento po mountu.

Izogibanje premikom postavitve

Pasice za soglasje so razvpite po povzročanju Cumulative Layout Shift (CLS), ključnega Core Web Vital kazalnika, ki vpliva na SEO uvrstitve. Ko se pasica pojavi po izrisu strani, potisne vsebino navzdol ali jo nepričakovano prekrije.

Strategije za zmanjšanje CLS zaradi pasic za soglasje:

Uporabite pasico na dnu: Pasice na dnu vidnega polja ne premikajo vsebine strani. To je najbolj prijazen pristop glede CLS.
Rezervirajte prostor: Če morate uporabiti pasico na vrhu, v CSS rezervirajte navpični prostor, da postavitev strani upošteva pasico še preden se izriše.
Izogibajte se modalnim prekrivnim oknom ob nalaganju: Celozaslonske stene za soglasje, ki se pojavijo po izrisu strani, povzročajo zaznano nestabilnost postavitve. Če potrebujete steno, jo izrišite kot del začetnega stanja strani.
Naložite CMP sinhrono v head: Ko je CMP naložen kot skript, ki blokira izris, v head, se lahko pasica pojavi kot del začetnega izrisa, namesto da bi se pojavila kasneje.

Ogrodno neodvisen pristop FlexyConsent

FlexyConsent je zasnovan tako, da deluje s katerim koli ogrodjem — ali brez ogrodja — tako, da deluje na ravni skriptov in ne na ravni komponent. Zakaj je to pomembno:

En sam async skriptni tag: Dovolj je ena oznaka <script> v <head>. Ni treba nameščati npm paketov, ni ogrodju specifičnih ovojev, ni konfiguracije gradnje.
Privzeta soglasja se sprožijo takoj: Skript kot prvo dejanje nastavi privzete vrednosti Consent Mode V2, še preden se izvede kakršen koli povratni klic ali manipulacija z DOM. To pomeni, da Google oznake spoštujejo soglasje od prve milisekunde naprej.
Brez odvisnosti od DOM: Logika soglasja ne čaka, da se React, Vue ali Svelte hidrirajo. Deluje neodvisno od življenjskega cikla ogrodja.
Deluje s SSG, SSR, ISR in CSR: Ker gre za navaden skript, deluje enako, ne glede na to, ali je bila stran statično generirana, strežniško izrisana, postopno regenerirana ali izrisana na strani odjemalca.

Nasvet za razvijalce: Najpreprostejši test pravilne integracije CMP je, da odprete zavihek Network v brskalniku, filtrirate po domenah Google in ponovno naložite stran. Nobena Google zahteva se ne sme sprožiti, preden se v konzoli pojavi ukaz za privzeto soglasje. Če se sprožijo, se vaš CMP nalaga prepozno.

Brezplačni paket FlexyConsent podpira neomejeno število ogledov strani in deluje z Next.js, Gatsby, Nuxt, Astro, SvelteKit, Remix in navadnim HTML. Integracija je pri vseh enaka: ena oznaka skripta, pravilno umeščena.