Pamoka2026 m. birželio 1 d. | FlexyConsent

Sutikimas dėl slapukų Next.js, Gatsby ir statiniuose puslapiuose: integracijos gidas programuotojams

Statinių svetainių sutikimo problema

Šiuolaikiniai JavaScript karkasai, tokie kaip Next.js, Gatsby ir Nuxt.js, iš esmės pakeitė, kaip kuriami ir pateikiami tinklalapiai. Puslapiai iš anksto atvaizduojami kompiliavimo metu arba serveryje, o tada kliente yra hidratuojami. Tai sukuria unikalų iššūkį sutikimui dėl slapukų: sutikimo juosta turi būti paruošta dar prieš vykdant bet kokius sekimo skriptus, tačiau pats puslapis jau gali būti atvaizduotas ir kešuojamas perimetre (edge).

Tradiciniai CMP buvo sukurti serveriu atvaizduojamiems PHP ar paprastiems HTML puslapiams, kuriuose dokumentas kraunamas linijiškai nuo viršaus iki apačios. Karkasų pasaulyje, kuriame yra kodo skaidymas, lazy loading ir srautinė server-side renderinimo technika, šios prielaidos nebegalioja. Teisingai įgyvendinti sutikimą tokiose aplinkose reiškia suprasti atvaizdavimo grandinę.

Kodėl laikas svarbesnis, nei manote

Standartiniame HTML puslapyje CMP skripto patalpinimas <head> dalyje prieš kitus skriptus yra paprastas. Next.js App Router ar Gatsby atveju situacija sudėtingesnė:

Pirmiausia atkeliauja iš anksto atvaizduotas HTML: Naršyklė gauna pilną HTML iš CDN ar serverio. Jei tame HTML yra įterptų inline skriptų ar trečiųjų šalių žymų, jos gali būti įvykdytos dar prieš įsikraunant jūsų sutikimo logikai.
Hidratacijos tarpas: React hidratacija įvyksta po to, kai HTML jau nupieštas. Jei jūsų sutikimo komponentas yra React komponentas, jis neveikia iki hidratacijos pabaigos. Šio tarpo metu Google žymos ar analitikos skriptai gali būti paleisti be sutikimo.
Perimetro kešavimo komplikacijos: Jei naudojate ISR (Incremental Static Regeneration) ar edge funkcijas, HTML yra kešuojamas. Negalite dinamiškai įterpti nuo sutikimo priklausančios logikos į kešuotą HTML be kliento pusės mechanizmo.

Pagrindinis principas toks: sutikimas turi būti valdomas skripto lygiu, o ne komponento lygiu. React komponentas, kuris atvaizduoja sutikimo juostą, yra per vėlus, jei tampa funkcionalus tik po hidratacijos.

Next.js App Router integracija

Next.js 13+ su App Router įvedė naują būdą, kaip tvarkyti skriptus. Štai rekomenduojamas požiūris į sutikimo integraciją:

1 žingsnis: įkelkite CMP skriptą šakniniame išdėstyme

Naudokite Next.js Script komponentą su beforeInteractive strategija savo šakniniame layout.tsx. Tai nurodo Next.js įterpti skriptą į pradinį HTML dokumentą dar prieš prasidedant hidratacijai:

beforeInteractive strategija yra kritiškai svarbi. Numatytoji afterInteractive strategija įkelia skriptus po hidratacijos, o tai sutikimui yra per vėlu. Naudojant beforeInteractive, CMP skriptas įtraukiamas į serverio atvaizduotą HTML ir vykdomas puslapiui kraunantis.

2 žingsnis: nustatykite numatytąjį sutikimą prieš Google žymas

Prieš jūsų Google Tag Manager ar gtag.js iškarpą įtraukite inline skriptą, kuris nustato numatytąsias sutikimo būsenas. Taip užtikrinama, kad net jei GTM įsikraus anksčiau, nei pasirodys CMP juosta, jis laikysis numatytųjų „atmesta“ reikšmių:

Šis inline skriptas turėtų būti patalpintas šakniniame išdėstyme <head> dalyje, prieš CMP ir GTM skriptus. Next.js aplinkoje tam galite naudoti įprastą <script> žymą <head> elemente.

3 žingsnis: maršrutų keitimų valdymas

Vieno puslapio aplikacijose (SPA) CMP skriptas įkeliamas vieną kart��, tačiau maršrutų keitimai nesukelia pilno puslapio perkrovimo. Jūsų CMP turi išlikti aktyvus per visus kliento pusės navigacijos pasikeitimus. FlexyConsent tai tvarko automatiškai — kartą įkeltas, jis lieka aktyvus visuose maršrutuose be pakartotinės inicijacijos.

Next.js Pages Router integracija

Projektams, kurie vis dar naudoja Pages Router, požiūris panašus, bet vietoje šakninio išdėstymo naudojamas _document.tsx. CMP skriptą patalpinkite savo pasirinktinio Document klasės <Head> komponente. beforeInteractive strategija Pages Router aplinkoje veikia taip pat.

Pagrindinis skirtumas tas, kad _document.tsx atvaizduojamas tik serveryje, todėl bet kokia čia esanti sutikimo logika garantuotai pateks į pradinį HTML atsaką.

Gatsby statinių svetainių integracija

Gatsby generuoja pilnai statinį HTML kompiliavimo metu. Užklausos metu serverio pusėje atvaizdavimo nėra, kas kai kuriuos dalykus supaprastina, o kitus apsunkina:

Naudokite gatsby-ssr.tsx, kad įterptumėte CMP skriptą į kiekvieno puslapio <head>. onRenderBody API leidžia pridėti skriptus į head dalį, kurie bus kiekviename statiniame HTML faile.
Venkite Gatsby įskiepių, kurie lazy-load’ina sutikimą: Kai kurie bendruomenės įskiepiai apgaubia sutikimą React komponentais, kurie prisimontuoja tik po hidratacijos. Tai sukuria jau minėtą laiko tarpą.
Sutikimo numatytuosius nustatymus dėkite inline: Naudokite setHeadComponents faile gatsby-ssr.tsx, kad pridėtumėte inline skriptą, nustatantį numatytąsias sutikimo būsenas. Šis skriptas bus statiniame HTML ir bus įvykdytas iškart.

Gatsby kompiliavimo metu generuojamas HTML reiškia, kad kiekvienas HTML failas jūsų CDN turės sutikimo skriptą. Tai iš tikrųjų idealu — nėra serverio logikos, kuri galėtų sugesti ar neteisingai kešuotis.

Nuxt.js ypatumai

Nuxt.js (paremtas Vue) turi savo šablonus. Nuxt 3 aplinkoje naudokite useHead composable arba nuxt.config.ts programos head konfigūraciją, kad globaliai pridėtumėte CMP skriptą. Nuxt palaiko parinktį body: false (skriptai patalpinami head dalyje) ir async atributą neblokuojančiam įkėlimui.

Nuxt server-side renderinimo režime galioja tas pats principas: CMP skriptas turi būti pradiniame HTML atsake, o ne dinamiškai įterptas Vue komponento po mount.

Išvengiant išdėstymo šuolių

Sutikimo juostos yra pagarsėjusios tuo, kad sukelia Cumulative Layout Shift (CLS), Core Web Vital rodiklį, kuris veikia SEO reitingus. Kai juosta iššoka po puslapio atvaizdavimo, ji nustumia turinį žemyn arba netikėtai jį uždengia.

Strategijos, kaip sumažinti CLS dėl sutikimo juostų:

Naudokite apačioje rodomą juostą: Apačioje vaizdo srities rodoma juosta nestumia puslapio turinio. Tai labiausiai CLS draugiškas sprendimas.
Rezervuokite vietą: Jei privalote naudoti viršuje esančią juostą, CSS’e rezervuokite jai vertikalią erdvę, kad puslapio išdėstymas ją įvertintų dar prieš atvaizdavimą.
Venkite modalinių perdangų įkrovos metu: Visą ekraną dengiančios sutikimo sienos, atsirandančios po puslapio atvaizdavimo, sukuria suvokiamą išdėstymo nestabilumą. Jei jums būtina siena, atvaizduokite ją kaip pradinę puslapio būseną.
Įkelkite CMP sinchroniškai head dalyje: Kai CMP įkeliamas kaip atvaizdavimą blokuojantis skriptas head dalyje, juosta gali pasirodyti kartu su pradiniu piešimu, o ne iššokti vėliau.

FlexyConsent karkasams neutralus požiūris

FlexyConsent sukurtas taip, kad veiktų su bet kuriuo karkasu — ar net be karkaso — veikdamas skripto, o ne komponento lygiu. Štai kodėl tai svarbu:

Vienintelė asinchroninė script žyma: Pakanka vienos <script> žymos <head> dalyje. Jokio npm paketų diegimo, jokių karkasui specifinių apvalkalų, jokios build konfigūracijos.
Sutikimo numatytieji nustatymai vykdomi iškart: Skriptas pirmiausia nustato Consent Mode V2 numatytuosius nustatymus, dar prieš bet kokius callback ar DOM manipuliacijas. Tai reiškia, kad Google žymos laikosi sutikimo nuo pirmosios milisekundės.
Nėra priklausomybės nuo DOM: Sutikimo logika nelaukia, kol React, Vue ar Svelte bus hidratuoti. Ji veikia nepriklausomai nuo karkaso gyvavimo ciklo.
Veikia su SSG, SSR, ISR ir CSR: Kadangi tai paprastas skriptas, jis identiškai veikia, nesvarbu, ar puslapis sugeneruotas statiniu būdu, atvaizduotas serveryje, inkrementiškai regeneruotas ar atvaizduotas kliento pusėje.

Programuotojo patarimas: Paprasčiausias testas, ar CMP integruotas teisingai, — atidarykite naršyklės Network skiltį, filtruokite pagal Google domenus ir perkraukite puslapį. Jokios Google užklausos neturėtų būti siunčiamos prieš pasirodant sutikimo numatytojo nustatymo komandai konsolėje. Jei jos vis dėlto siunčiamos, jūsų CMP įsikrauna per vėlai.

FlexyConsent nemokamas planas palaiko neribotą puslapių peržiūrų skaičių ir veikia su Next.js, Gatsby, Nuxt, Astro, SvelteKit, Remix ir paprastu HTML. Integracija visur vienoda: viena script žyma, tinkamai patalpinta.