Õpetus1. juuni 2026 | FlexyConsent

Küpsiste nõusolek Next.js, Gatsby ja staatiliste saitide jaoks: arendaja integratsioonijuhend

Staatiliste saitide nõusoleku probleem

Kaasaegsed JavaScripti raamistikud nagu Next.js, Gatsby ja Nuxt.js tõid kaasa paradigma muutuse selles, kuidas veebilehti ehitatakse ja tarnitakse. Lehed renderdatakse eelnevalt ehituse ajal või serveris ning seejärel hüdreeritakse kliendil. See tekitab küpsiste nõusoleku jaoks ainulaadse väljakutse: nõusolekuriba peab olema valmis enne, kui ükski jälgimisskript käivitub, kuid leht ise võib juba olla renderdatud ja servas vahemällu salvestatud.

Traditsioonilised CMP-d loodi serveris renderdatud PHP või lihtsate HTML-lehtede jaoks, kus dokument laetakse lineaarselt ülalt alla. Raamistike maailmas, kus on koodijagamine, laisklaadimine ja voogedastav serveripoolne renderdamine, need eeldused ei kehti. Nõusoleku korrektne rakendamine nendes keskkondades eeldab renderdamise torujuhtme mõistmist.

Miks ajastus on olulisem, kui arvad

Tavalises HTML-lehes on CMP skripti paigutamine <head> sektsiooni enne teisi skripte lihtne. Next.js App Routeri või Gatsby puhul on olukord keerulisem:

Eelrenderdatud HTML jõuab esimesena: Brauser saab täieliku HTML-i CDN-ist või serverist. Kui sellesse HTML-i on lisatud inline-skripte või kolmandate osapoolte silte, võivad need käivituda enne, kui sinu nõusolekuloogika laeb.
Hüdreerimise vahe: Reacti hüdreerimine toimub pärast seda, kui HTML on ekraanile joonistatud. Kui sinu nõusolekukomponent on Reacti komponent, ei eksisteeri see funktsionaalses olekus enne hüdreerimise lõppemist. Selle vahe ajal võivad Google’i sildid või analüütikaskriptid ilma nõusolekuta käivituda.
Serva-vahemälu keerukus: Kui kasutad ISR-i (Incremental Static Regeneration) või edge-funktsioone, on HTML vahemällu salvestatud. Sa ei saa dünaamiliselt süstida nõusolekust sõltuvat loogikat vahemällu salvestatud HTML-i ilma kliendipoolse mehhanismita.

Põhiprintsiip on järgmine: nõusolek tuleb kehtestada skripti tasemel, mitte komponendi tasemel. Reacti komponent, mis renderdab nõusolekuriba, on liiga hilja, kui see muutub interaktiivseks alles pärast hüdreerimist.

Next.js App Routeri integreerimine

Next.js 13+ koos App Routeriga tõi uue viisi skriptide käsitlemiseks. Siin on soovitatav lähenemine nõusoleku integreerimiseks:

Samm 1: Laadi CMP skript juurpaigutuses

Kasuta Next.js Script komponenti koos beforeInteractive strateegiaga oma juure layout.tsx failis. See ütleb Next.js-le, et skript süstitaks algsesse HTML-dokumenti enne hüdreerimise algust:

beforeInteractive strateegia on kriitiline. Vaikimisi afterInteractive strateegia laeb skriptid pärast hüdreerimist, mis on nõusoleku jaoks liiga hilja. beforeInteractive korral lisatakse CMP skript serveris renderdatud HTML-i ja see käivitub lehe laadimisel.

Samm 2: Sea vaikimisi nõusolek enne Google’i silte

Enne oma Google Tag Manageri või gtag.js lõiku lisa inline-skript, mis seab vaikimisi nõusoleku olekud. See tagab, et isegi kui GTM laeb enne, kui CMP riba ilmub, järgib see keelatud vaikeseadeid:

See inline-skript tuleks paigutada juurpaigutuse <head> sektsiooni enne CMP ja GTM skripte. Next.js-is saad selleks kasutada tavalist <script> silti oma paigutuse <head> elemendi sees.

Samm 3: Ruuterivahetuste käsitlemine

Ühelehe-rakenduse navigeerimisel laetakse CMP skript ainult korra, kuid ruuteri vahetused ei käivita täielikku lehe uuesti laadimist. Sinu CMP peab püsima kliendipoolsete navigeerimiste vahel. FlexyConsent käsitleb seda automaatselt — kui see on kord laetud, jääb see aktiivseks kõigi ruuterivahetuste ajal ilma uuesti initsialiseerimiseta.

Next.js Pages Routeri integreerimine

Projektide puhul, mis kasutavad endiselt Pages Routerit, on lähenemine sarnane, kuid kasutab juurpaigutuse asemel faili _document.tsx. Paiguta CMP skript oma kohandatud Document klassi <Head> komponenti. beforeInteractive strateegia töötab Pages Routeris samamoodi.

Põhierinevus on see, et _document.tsx renderdatakse ainult serveris, seega on kogu siin olev nõusolekuloogika garanteeritult algses HTML-paketis.

Gatsby staatilise saidi integreerimine

Gatsby genereerib täielikult staatilise HTML-i ehituse ajal. Päringu ajal serveripoolset renderdamist ei toimu, mis lihtsustab mõningaid aspekte, kuid muudab teised keerulisemaks:

Kasuta gatsby-ssr.tsx faili, et süstida CMP skript iga lehe <head> sektsiooni. onRenderBody API võimaldab lisada päisesse skripte, mis on olemas igas staatilises HTML-failis.
Väldi Gatsby pluginaid, mis laevad nõusoleku laisalt: Mõned kogukonna pluginad mähivad nõusoleku Reacti komponentidesse, mis monteeritakse alles pärast hüdreerimist. See tekitab eespool kirjeldatud ajastuse vahe.
Paiguta nõusoleku vaikeseaded inline: Kasuta setHeadComponents funktsiooni failis gatsby-ssr.tsx, et lisada inline-skript, mis seab vaikimisi nõusoleku olekud. See skript on staatilises HTML-is ja käivitub kohe.

Gatsby ehitusajal põhinev lähenemine tähendab, et iga HTML-fail sinu CDN-is sisaldab nõusolekuskripti. See on tegelikult ideaalne — puudub serveriloogika, mis võiks ebaõnnestuda või valesti vahemällu salvestada.

Nuxt.js eripärad

Nuxt.js (Vue-põhine) kasutab oma mustreid. Nuxt 3 puhul kasuta useHead composable’it või nuxt.config.ts faili rakenduse päise konfiguratsiooni, et lisada CMP skript globaalselt. Nuxt toetab valikut body: false (mis paigutab skriptid päisesse) ja async atribuuti mitteblokeerivaks laadimiseks.

Nuxti serveripoolse renderdamise režiimis kehtib sama põhimõte: CMP skript peab olema algses HTML-vastuses, mitte Vue komponendi poolt pärast mount’i dünaamiliselt süstitud.

Paigutuse nihke vältimine

Nõusolekuribad on kurikuulsad selle poolest, et põhjustavad Cumulative Layout Shift (CLS) näitajat, mis on üks Core Web Vitals mõõdikuid ja mõjutab SEO positsioone. Kui riba ilmub pärast lehe renderdamist, lükkab see sisu alla või katab selle ootamatult.

Strateegiad, et minimeerida nõusolekuribade põhjustatud CLS-i:

Kasuta allserva paigutatud riba: Vaateakna allservas olevad ribad ei nihuta lehe sisu. See on CLS-i mõttes kõige sõbralikum lahendus.
Broneeri ruum: Kui pead kasutama ülaserva riba, broneeri selle jaoks vertikaalne ruum oma CSS-is, et lehe paigutus arvestaks ribaga juba enne selle renderdamist.
Väldi laadimisel modaalaknaid: Täisekraanilised nõusolekuseinad, mis ilmuvad pärast lehe renderdamist, tekitavad tajutavat paigutuse ebastabiilsust. Kui vajad seina, renderda see algse lehe oleku osana.
Laadi CMP sünkroonselt päises: Kui CMP laetakse renderdamist blokeeriva skriptina päises, saab riba ilmuda koos algse joonistusega, mitte hiljem „hüpata“.

FlexyConsenti raamistikusõltumatu lähenemine

FlexyConsent on loodud töötama mis tahes raamistikuga — või üldse ilma raamistikuta — tegutsedes skripti tasemel, mitte komponendi tasemel. Miks see oluline on:

Üks asünkroonne skriptisilt: Vaid üks <script> silt <head> sektsioonis on kõik, mida vajad. Pole vaja paigaldada npm pakette, pole raamistikuspetsiifilisi ümbriseid ega ehituskonfiguratsiooni.
Nõusoleku vaikeseaded käivituvad kohe: Skript seab Consent Mode V2 vaikeseaded oma esimese tegevusena, enne mis tahes callback’i või DOM-i manipuleerimist. See tähendab, et Google’i sildid arvestavad nõusolekut esimesest millisekundist alates.
Pole DOM-i sõltuvust: Nõusolekuloogika ei oota Reacti, Vue ega Svelte hüdreerimist. See töötab sõltumatult raamistikutsüklist.
Töötab SSG, SSR, ISR ja CSR korral: Kuna tegu on tavalise skriptiga, toimib see identselt sõltumata sellest, kas leht on staatiliselt genereeritud, serveris renderdatud, inkrementaalselt regenereeritud või kliendipoolselt renderdatud.

Arendaja nipp: Lihtsaim test CMP õige integreerimise kontrollimiseks on avada brauseri Network sakk, filtreerida Google’i domeenide järgi ja laadida leht uuesti. Ühtegi Google’i päringut ei tohi käivituda enne, kui konsoolis ilmub nõusoleku vaikekäsu logi. Kui need siiski käivituvad, laeb sinu CMP liiga hilja.

FlexyConsenti tasuta pakett toetab piiramatuid lehevaatamisi ja töötab koos Next.js, Gatsby, Nuxt, Astro, SvelteKit, Remix ja tavalise HTML-iga. Integratsioon on kõigi puhul sama: üks õigesti paigutatud skriptisilt.