Opas1. kesäkuuta 2026 | FlexyConsent

Evästesuostumus Next.js-, Gatsby- ja staattisille sivustoille: kehittäjän integraatio-opas

Staattisten sivustojen suostumusongelma

Modernit JavaScript-kehykset kuten Next.js, Gatsby ja Nuxt.js ovat tuoneet mukanaan paradigman muutoksen siihen, miten verkkosivuja rakennetaan ja toimitetaan. Sivut esirenderöidään rakennusvaiheessa tai palvelimella, ja ne hydratoidaan selaimessa. Tämä luo evästesuostumukselle ainutlaatuisen haasteen: suostumusbannerin on oltava valmiina ennen kuin yksikään seurantaskripti suoritetaan, mutta itse sivu voi olla jo renderöity ja välimuistissa reunapalvelimilla.

Perinteiset CMP-ratkaisut suunniteltiin palvelinrenderöidyille PHP- tai yksinkertaisille HTML-sivuille, joissa dokumentti latautuu lineaarisesti ylhäältä alas. Kehysmaailmassa, jossa on koodin pilkkomista, laiskaa latausta ja suoratoistavaa palvelinpuolen renderöintiä, nämä oletukset eivät enää päde. Suostumuksen toteuttaminen oikein tällaisissa ympäristöissä edellyttää renderöintiputken ymmärtämistä.

Miksi ajoitus on tärkeämpää kuin uskotkaan

Tavallisella HTML-sivulla CMP-skriptin sijoittaminen <head>-osioon ennen muita skriptejä on suoraviivaista. Next.js App Routerissa tai Gatsbyssa tilanne on monimutkaisempi:

Esirenderöity HTML saapuu ensin: Selain vastaanottaa valmiin HTML:n CDN:ltä tai palvelimelta. Jos HTML:ään on upotettu inline-skriptejä tai kolmannen osapuolen tageja, ne voivat suorittua ennen kuin suostumuslogiikkasi latautuu.
Hydraatiokuilu: React-hydraatio tapahtuu sen jälkeen, kun HTML on piirretty ruudulle. Jos suostumuskomponenttisi on React-komponentti, se ei ole toiminnallinen ennen hydraation valmistumista. Tämän kuilun aikana Google-tagit tai analytiikkaskriptit voivat laukaista ilman suostumusta.
Reunavälimuistin haasteet: Jos käytät ISR:ää (Incremental Static Regeneration) tai edge-funktioita, HTML on välimuistissa. Et voi dynaamisesti ruiskuttaa suostumuksesta riippuvaa logiikkaa välimuistissa olevaan HTML:ään ilman selainpuolen mekanismia.

Perusperiaate on tämä: suostumus on määritettävä skriptitasolla, ei komponenttitasolla. React-komponentti, joka renderöi suostumusbannerin, on liian myöhässä, jos se muuttuu interaktiiviseksi vasta hydraation jälkeen.

Next.js App Router -integraatio

Next.js 13+ App Router toi uuden tavan käsitellä skriptejä. Tässä suositeltu lähestymistapa suostumuksen integrointiin:

Vaihe 1: Lataa CMP-skripti juurilayoutissa

Käytä Next.js:n Script-komponenttia beforeInteractive-strategialla juuren layout.tsx-tiedostossa. Tämä kertoo Next.js:lle, että skripti ruiskutetaan alkuperäiseen HTML-dokumenttiin ennen hydraation alkamista:

beforeInteractive-strategia on kriittinen. Oletusstrategia afterInteractive lataa skriptit hydraation jälkeen, mikä on liian myöhäistä suostumuksen kannalta. beforeInteractive-strategialla CMP-skripti sisällytetään palvelinrenderöityyn HTML:ään ja suoritetaan sivun latautuessa.

Vaihe 2: Aseta oletussuostumukset ennen Google-tageja

Ennen Google Tag Manager- tai gtag.js-katkelmaa lisää inline-skripti, joka asettaa oletussuostumustilat. Näin varmistetaan, että vaikka GTM latautuisi ennen kuin CMP-banneri ilmestyy, se noudattaa kiellettyjä oletuksia:

Tämä inline-skripti tulisi sijoittaa juurilayoutin <head>-osioon ennen CMP- ja GTM-skriptejä. Next.js:ssä voit käyttää tavallista <script>-tagia layoutin <head>-elementin sisällä tähän tarkoitukseen.

Vaihe 3: Käsittele reitin vaihdot

Single-page-sovelluksen navigaatiossa CMP-skripti ladataan kerran, mutta reitin vaihdot eivät laukaise koko sivun uudelleenlatausta. CMP:n on säilyttävä toiminnassa myös selainpuolen navigaatioiden yli. FlexyConsent hoitaa tämän automaattisesti — kun se on kerran ladattu, se pysyy aktiivisena kaikissa reitin vaihdoissa ilman uudelleenkäynnistystä.

Next.js Pages Router -integraatio

Projekteissa, jotka käyttävät yhä Pages Routeria, lähestymistapa on samankaltainen, mutta käyttää juurilayoutin sijasta tiedostoa _document.tsx. Sijoita CMP-skripti mukautetun Document-luokan <Head>-komponenttiin. beforeInteractive-strategia toimii samalla tavalla Pages Routerissa.

Keskeinen ero on se, että _document.tsx renderöidään vain palvelimella, joten kaikki siellä oleva suostumuslogiikka on taatusti mukana alkuperäisessä HTML-payloadissa.

Gatsby-staattisen sivuston integraatio

Gatsby generoi täysin staattisen HTML:n rakennusvaiheessa. Pyyntöhetkellä ei ole palvelinpuolen renderöintiä, mikä yksinkertaistaa joitakin asioita mutta monimutkaistaa toisia:

Käytä gatsby-ssr.tsx-tiedostoa ruiskuttaaksesi CMP-skriptin jokaisen sivun <head>-osioon. onRenderBody-API:n avulla voit lisätä head-komponentteja, jotka ovat mukana jokaisessa staattisessa HTML-tiedostossa.
Vältä Gatsby-lisäosia, jotka lataavat suostumuksen laiskasti: Jotkin yhteisön lisäosat kietovat suostumuksen React-komponentteihin, jotka mountataan vasta hydraation jälkeen. Tämä luo aiemmin kuvatun ajoituskuilun.
Sijoita oletussuostumukset inline-skriptinä: Käytä setHeadComponents-funktiota tiedostossa gatsby-ssr.tsx lisätäksesi inline-skriptin, joka asettaa oletussuostumustilat. Tämä skripti on staattisessa HTML:ssä ja suoritetaan välittömästi.

Gatsbyn rakennusaikainen lähestymistapa tarkoittaa, että jokainen CDN:llä oleva HTML-tiedosto sisältää suostumusskriptin. Tämä on itse asiassa ihanteellista — ei ole palvelinlogiikkaa, joka voisi epäonnistua tai välimuistittua väärin.

Nuxt.js-huomiot

Nuxt.js (Vue-pohjainen) käyttää omia mallejaan. Nuxt 3:ssa käytä useHead-composablea tai nuxt.config.ts-tiedoston app head -konfiguraatiota lisätäksesi CMP-skriptin globaalisti. Nuxt tukee body: false -valintaa (joka sijoittaa skriptit head-osioon) sekä async-attribuuttia ei-blokkaavaan lataukseen.

Nuxtin palvelinpuolen renderöintitilassa pätee sama periaate: CMP-skriptin on oltava mukana alkuperäisessä HTML-vastauksessa, ei Vue-komponentin dynaamisesti injektoimana mount-vaiheen jälkeen.

Layout-shiftin välttäminen

Suostumusbannerit ovat pahamaineisia siitä, että ne aiheuttavat Cumulative Layout Shift (CLS) -ilmiötä, joka on Core Web Vitals -mittari ja vaikuttaa SEO-sijoituksiin. Kun banneri ilmestyy vasta sivun renderöitymisen jälkeen, se työntää sisältöä alaspäin tai peittää sitä odottamattomasti.

Strategioita CLS:n minimoimiseksi suostumusbannereissa:

Käytä alalaitaan sijoitettua banneria: Näkymän alareunassa olevat bannerit eivät siirrä sivun sisältöä. Tämä on CLS:n kannalta ystävällisin ratkaisu.
Varaa tila etukäteen: Jos sinun on käytettävä yläreunan banneria, varaa sen tarvitsema pystysuuntainen tila CSS:llä, jotta sivun layout huomioi bannerin jo ennen sen renderöitymistä.
Vältä modaalisia overlay-ikkunoita latauksen yhteydessä: Koko ruudun suostumusseinät, jotka ilmestyvät sivun renderöitymisen jälkeen, aiheuttavat koettua layoutin epävakautta. Jos tarvitset seinän, renderöi se osana sivun alkuperäistä tilaa.
Lataa CMP synkronisesti head-osiossa: Kun CMP ladataan renderöintiä blokkaavana skriptinä head-osiossa, banneri voi ilmestyä osana ensimmäistä maalausta sen sijaan, että se pompahtaisi näkyviin myöhemmin.

FlexyConsentin kehysriippumaton lähestymistapa

FlexyConsent on suunniteltu toimimaan minkä tahansa kehyksen — tai ilman kehystä — kanssa toimimalla skriptitasolla komponenttitason sijaan. Tästä syystä tämä on tärkeää:

Yksi asynkroninen script-tagi: Yksi <script>-tunniste <head>-osiossa riittää. Ei npm-paketteja asennettavaksi, ei kehyskohtaisia wrappeja, ei build-konfiguraatiota.
Oletussuostumukset laukeavat välittömästi: Skripti asettaa Consent Mode V2 -oletukset ensimmäisenä toimenpiteenään ennen mitään callbackeja tai DOM-manipulaatiota. Tämä tarkoittaa, että Google-tagit noudattavat suostumusta ensimmäisestä millisekunnista lähtien.
Ei DOM-riippuvuutta: Suostumuslogiikka ei odota React-, Vue- tai Svelte-kehyksen hydraatiota. Se toimii riippumatta kehyksen elinkaaresta.
Toimii SSG-, SSR-, ISR- ja CSR-malleissa: Koska kyseessä on tavallinen skripti, se toimii identtisesti riippumatta siitä, onko sivu generoitu staattisesti, renderöity palvelimella, regeneroitu inkrementaalisesti vai renderöity selainpuolella.

Kehittäjävinkki: Yksinkertaisin testi CMP-integraation oikeellisuudelle on avata selaimen Network-välilehti, suodattaa Google-domainit ja ladata sivu uudelleen. Yhtään Google-pyyntöä ei pitäisi lähteä ennen kuin suostumuksen oletuskomento näkyy konsolissa. Jos pyyntöjä lähtee, CMP latautuu liian myöhään.

FlexyConsentin ilmainen paketti tukee rajatonta sivunäyttömäärää ja toimii Next.js-, Gatsby-, Nuxt-, Astro-, SvelteKit-, Remix- ja tavallisten HTML-sivujen kanssa. Integraatio on sama kaikissa: yksi script-tagi, joka on sijoitettu oikein.