TutorialHunyo 1, 2026 | FlexyConsent

Cookie Consent para sa Next.js, Gatsby, at mga Static Site: Isang Gabay sa Integrasyon para sa mga Developer

Ang Problema ng Consent sa mga Static Site

Ang mga modernong JavaScript framework tulad ng Next.js, Gatsby, at Nuxt.js ay nagdala ng malaking pagbabago sa paraan ng pagbuo at pag-deliver ng mga web page. Ang mga page ay pre-rendered sa build time o sa server, tapos ay hini-hydrate sa client. Nagdudulot ito ng natatanging hamon para sa cookie consent: kailangang handa na ang consent banner bago tumakbo ang anumang tracking script, pero ang mismong page ay maaaring rendered na at naka-cache sa edge.

Ang mga tradisyonal na CMP ay dinisenyo para sa server-rendered na PHP o simpleng HTML page kung saan linearly na naglo-load ang dokumento mula itaas pababa. Sa mundo ng mga framework na may code splitting, lazy loading, at streaming server-side rendering, nababasag ang mga dating assumption. Para maayos ang consent sa ganitong mga environment, kailangan mong maintindihan ang rendering pipeline.

Bakit Mas Kritikal ang Timing Kaysa sa Akala Mo

Sa isang karaniwang HTML page, madali lang ilagay ang CMP script sa <head> bago ang ibang script. Sa Next.js App Router o Gatsby, mas kumplikado ang sitwasyon:

Nauna ang pre-rendered HTML: Tumatanggap ang browser ng kumpletong HTML mula sa CDN o server. Kung may mga inline script o third-party tag na naka-embed sa HTML na iyon, maaari na silang tumakbo bago ma-load ang consent logic mo.
Hydration gap: Nangyayari ang React hydration pagkatapos ma-paint ang HTML. Kung ang consent component mo ay isang React component, hindi pa ito functional hanggang makumpleto ang hydration. Sa gap na ito, puwedeng mag-fire ang mga Google tag o analytics script nang walang consent.
Mga komplikasyon sa edge caching: Kung gumagamit ka ng ISR (Incremental Static Regeneration) o edge function, naka-cache ang HTML. Hindi mo basta-basta ma-i-inject nang dynamic ang consent-dependent logic sa naka-cache na HTML nang walang client-side na mekanismo.

Ang pangunahing prinsipyo ay ito: dapat maitatag ang consent sa antas ng script, hindi sa antas ng component. Huli na ang isang React component na nagre-render ng consent banner kung magiging interactive lang ito pagkatapos ng hydration.

Integrasyon sa Next.js App Router

Ang Next.js 13+ na may App Router ay nagpakilala ng bagong paraan sa paghawak ng mga script. Narito ang inirerekomendang approach para sa consent integration:

Hakbang 1: I-load ang CMP Script sa Root Layout

Gamitin ang Next.js na Script component na may beforeInteractive strategy sa iyong root layout.tsx. Sinasabi nito sa Next.js na i-inject ang script sa initial HTML document, bago magsimula ang hydration:

Kritikal ang beforeInteractive strategy. Ang default na afterInteractive strategy ay naglo-load ng mga script pagkatapos ng hydration, na masyadong huli para sa consent. Sa beforeInteractive, kasama ang CMP script sa server-rendered HTML at tumatakbo habang naglo-load ang page.

Hakbang 2: Itakda ang Default Consent Bago ang mga Google Tag

Bago ang iyong Google Tag Manager o gtag.js snippet, maglagay ng inline script na nagse-set ng default consent states. Tinitiyak nito na kahit ma-load ang GTM bago lumitaw ang CMP banner, irerespeto nito ang mga default na naka-deny:

Dapat ilagay ang inline script na ito sa <head> ng iyong root layout, bago ang CMP at GTM scripts. Sa Next.js, maaari kang gumamit ng regular na <script> tag sa loob ng <head> element ng layout mo para dito.

Hakbang 3: I-handle ang mga Pagbabago ng Route

Sa single-page application navigation, isang beses lang naglo-load ang CMP script pero ang mga route change ay hindi nagti-trigger ng full page reload. Dapat mag-persist ang CMP mo sa mga client-side navigation. Awtomatikong hinahandle ito ng FlexyConsent — kapag na-load na, nananatili itong aktibo sa lahat ng route change nang walang re-initialization.

Integrasyon sa Next.js Pages Router

Para sa mga proyektong gumagamit pa ng Pages Router, halos pareho ang approach pero gumagamit ng _document.tsx sa halip na root layout. Ilagay ang CMP script sa <Head> component ng iyong custom Document class. Pareho ang pag-andar ng beforeInteractive strategy sa Pages Router.

Ang pangunahing kaibahan ay ang _document.tsx ay nirender lang sa server, kaya anumang consent logic dito ay garantisadong kasama sa initial HTML payload.

Integrasyon sa Gatsby Static Site

Ang Gatsby ay gumagawa ng fully static HTML sa build time. Walang server-side rendering sa request time, na nagpapasimple sa ilang bagay pero nagpapakumplikado rin sa iba:

Gamitin ang gatsby-ssr.tsx para i-inject ang CMP script sa <head> ng bawat page. Pinapayagan ka ng onRenderBody API na magdagdag ng mga script sa head na magiging bahagi ng bawat static HTML file.
Iwasan ang mga Gatsby plugin na nagla-lazy-load ng consent: May ilang community plugin na binabalot ang consent sa mga React component na nagmo-mount lang pagkatapos ng hydration. Lumilikha ito ng timing gap na tinalakay natin kanina.
Ilagay ang consent defaults bilang inline: Gamitin ang setHeadComponents sa gatsby-ssr.tsx para magdagdag ng inline script na nagse-set ng default consent states. Mapupunta ang script na ito sa static HTML at agad na tatakbo.

Ang build-time approach ng Gatsby ay nangangahulugang bawat HTML file sa iyong CDN ay may kasamang consent script. Sa katunayan, ideal ito — walang server logic na puwedeng pumalya o mag-cache nang mali.

Mga Dapat Isaalang-alang sa Nuxt.js

May sarili ring pattern ang Nuxt.js (na nakabatay sa Vue). Sa Nuxt 3, gamitin ang useHead composable o ang nuxt.config.ts app head configuration para idagdag ang CMP script nang global. Sinusuportahan ng Nuxt ang body: false option (na naglalagay ng mga script sa head) at ang async attribute para sa non-blocking loading.

Para sa server-side rendering mode ng Nuxt, pareho ang prinsipyo: kailangang nasa initial HTML response ang CMP script, hindi ini-inject nang dynamic ng isang Vue component pagkatapos ng mount.

Pag-iwas sa Layout Shift

Kilala ang mga consent banner sa pagdulot ng Cumulative Layout Shift (CLS), isang Core Web Vital na nakaaapekto sa SEO rankings. Kapag biglang lumitaw ang banner pagkatapos ma-render ang page, itinutulak nito ang content pababa o biglaang nag-o-overlay.

Mga estratehiya para mabawasan ang CLS mula sa mga consent banner:

Gumamit ng banner sa ibaba: Ang mga banner sa ibabang bahagi ng viewport ay hindi nagtutulak ng page content. Ito ang pinaka-CLS-friendly na approach.
Magreserba ng espasyo: Kung kailangan mong gumamit ng top banner, magreserba ng vertical space sa iyong CSS para ma-account ng page layout ang banner bago ito ma-render.
Iwasan ang modal overlay sa load: Ang mga full-screen consent wall na lumilitaw pagkatapos ma-render ang page ay nagdudulot ng perceived layout instability. Kung kailangan mo ng wall, i-render ito bilang bahagi ng initial page state.
I-load ang CMP nang synchronous sa head: Kapag ang CMP ay naka-load bilang render-blocking script sa head, puwede nang lumitaw ang banner bilang bahagi ng initial paint sa halip na biglang sumulpot nang huli.

Framework-Agnostic na Approach ng FlexyConsent

Dinisenyo ang FlexyConsent para gumana sa anumang framework — o kahit walang framework — sa pamamagitan ng pag-operate sa antas ng script sa halip na component. Narito kung bakit ito mahalaga:

Isang async script tag lang: Isang <script> tag lang sa <head> ang kailangan. Walang kailangang i-install na npm package, walang framework-specific wrapper, walang build configuration.
Agad na tumatakbo ang consent defaults: Itinatakda ng script ang Consent Mode V2 defaults bilang unang aksyon nito, bago anumang callback o DOM manipulation. Ibig sabihin, iginagalang na ng mga Google tag ang consent mula sa pinakaunang millisecond.
Walang dependency sa DOM: Hindi naghihintay ang consent logic sa hydration ng React, Vue, o Svelte. Gumagana ito nang hiwalay sa lifecycle ng framework.
Gumagana sa SSG, SSR, ISR, at CSR: Dahil isa lang itong plain script, pareho ang pag-andar nito kahit statically generated, server-rendered, incrementally regenerated, o client-side rendered ang page.

Tip para sa developer: Ang pinakasimpleng test para sa tamang CMP integration ay buksan ang Network tab ng browser mo, i-filter sa mga Google domain, at i-reload ang page. Hindi dapat may anumang Google request na mag-fire bago lumitaw ang consent default command sa console. Kung meron, masyadong huli naglo-load ang CMP mo.

Sinusuportahan ng libreng plano ng FlexyConsent ang unlimited pageviews at gumagana ito sa Next.js, Gatsby, Nuxt, Astro, SvelteKit, Remix, at plain HTML. Pareho ang integrasyon sa lahat ng ito: isang script tag, na maayos ang pagkakalagay.