Tutorial1 qershor 2026 | FlexyConsent

Cookie Consent për Next.js, Gatsby dhe faqe statike: Udhëzues integrimi për zhvillues

Problemi i Consent për faqet statike

Kuadrot moderne JavaScript si Next.js, Gatsby dhe Nuxt.js sollën një ndryshim paradigme në mënyrën se si ndërtohen dhe shpërndahen faqet e uebit. Faqet para-renderohen në kohën e ndërtimit ose në server, pastaj hidratohen në klient. Kjo krijon një sfidë unike për cookie consent: baneri i consent duhet të jetë gati përpara se të ekzekutohet ndonjë script gjurmimi, por vetë faqja mund të jetë tashmë e renderuar dhe e cache-uar në edge.

CMP-të tradicionale janë projektuar për faqe të renderuara në server me PHP ose faqe të thjeshta HTML ku dokumenti ngarkohet në mënyrë lineare nga lart-poshtë. Në një botë kuadrosh me code splitting, lazy loading dhe streaming server-side rendering, këto supozime bien poshtë. Ta bësh consent-in siç duhet në këto mjedise kërkon të kuptosh pipeline-in e renderimit.

Pse koha ka më shumë rëndësi nga sa mendoni

Në një faqe standarde HTML, vendosja e një CMP script në <head> përpara skripteve të tjera është e drejtpërdrejtë. Në Next.js App Router ose Gatsby, situata është më komplekse:

HTML e para-renderuar vjen e para: Shfletuesi merr HTML të plotë nga CDN ose serveri. Nëse ndonjë script inline ose tag palë të treta është i futur në atë HTML, mund të ekzekutohet përpara se logjika juaj e consent të ngarkohet.
Hapësira e hydration: Hydration i React ndodh pasi HTML është pikturuar. Nëse komponenti juaj i consent është një komponent React, ai nuk ekziston në gjendje funksionale derisa të përfundojë hydration. Gjatë kësaj hapësire, tag-et e Google ose skriptet e analitikës mund të ekzekutohen pa consent.
Ndërlikimet nga edge caching: Nëse përdorni ISR (Incremental Static Regeneration) ose edge functions, HTML cache-ohet. Nuk mund të injektoni në mënyrë dinamike logjikë të varur nga consent në HTML të cache-uar pa një mekanizëm në anën e klientit.

Parimi bazë është ky: consent duhet të vendoset në nivel script-i, jo në nivel komponenti. Një komponent React që renderon një baner consent është shumë vonë nëse bëhet interaktiv vetëm pasi të ketë përfunduar hydration.

Integrimi me Next.js App Router

Next.js 13+ me App Router prezantoi një mënyrë të re për të trajtuar skriptet. Ja qasja e rekomanduar për integrimin e consent:

Hapi 1: Ngarkoni CMP Script në Root Layout

Përdorni komponentin Script të Next.js me strategjinë beforeInteractive në layout.tsx rrënjë. Kjo i thotë Next.js të injektojë script-in në dokumentin fillestar HTML, përpara se të nisë hydration:

Strategjia beforeInteractive është kritike. Strategjia e parazgjedhur afterInteractive i ngarkon skriptet pas hydration, që është shumë vonë për consent. Me beforeInteractive, CMP script përfshihet në HTML të renderuar në server dhe ekzekutohet ndërsa faqja ngarkohet.

Hapi 2: Vendosni consent-in e parazgjedhur përpara Google Tags

Përpara snippet-it tuaj të Google Tag Manager ose gtag.js, përfshini një script inline që vendos gjendjet e parazgjedhura të consent. Kjo siguron që edhe nëse GTM ngarkohet përpara se të shfaqet baneri i CMP, ai respekton vlerat e refuzuara të parazgjedhura:

Ky script inline duhet të vendoset në <head> të layout-it tuaj rrënjë, përpara skripteve CMP dhe GTM. Në Next.js, mund të përdorni një tag të zakonshëm <script> brenda elementit <head> të layout-it për këtë qëllim.

Hapi 3: Trajtoni ndryshimet e rrugeve

Në navigimin single-page application, CMP script ngarkohet një herë, por ndryshimet e rrugeve nuk shkaktojnë reload të plotë të faqes. CMP juaj duhet të qëndrojë i pranishëm në të gjitha navigimet në anën e klientit. FlexyConsent e trajton këtë automatikisht — sapo të ngarkohet, mbetet aktiv në të gjitha ndryshimet e rrugeve pa ri-inicializim.

Integrimi me Next.js Pages Router

Për projekte që ende përdorin Pages Router, qasja është e ngjashme, por përdor _document.tsx në vend të root layout. Vendosni CMP script në komponentin <Head> të klasës suaj custom Document. Strategjia beforeInteractive funksionon njësoj në Pages Router.

Dallimi kryesor është se _document.tsx renderohet vetëm në server, kështu që çdo logjikë consent këtu është e garantuar të jetë në payload-in fillestar HTML.

Integrimi statik me Gatsby

Gatsby gjeneron HTML plotësisht statik në kohën e ndërtimit. Nuk ka server-side rendering në kohën e kërkesës, gjë që thjeshton disa aspekte, por i ndërlikon të tjerat:

Përdorni gatsby-ssr.tsx për të injektuar CMP script në <head> të çdo faqeje. API onRenderBody ju lejon të shtoni skripte në head që do të jenë të pranishme në çdo skedar statik HTML.
Shmangni plugin-et e Gatsby që e ngarkojnë consent me vonesë: Disa plugin-e të komunitetit e mbështjellin consent në komponentë React që montohen vetëm pas hydration. Kjo krijon hapësirën kohore të përmendur më herët.
Vendosni vlerat e parazgjedhura të consent inline: Përdorni setHeadComponents në gatsby-ssr.tsx për të shtuar një script inline që vendos gjendjet e parazgjedhura të consent. Ky script do të jetë në HTML statik dhe do të ekzekutohet menjëherë.

Qasja e Gatsby në kohën e ndërtimit do të thotë që çdo skedar HTML në CDN-në tuaj do të përfshijë script-in e consent. Kjo në fakt është ideale — nuk ka logjikë serveri që të dështojë ose të cache-ohet gabim.

Konsiderata për Nuxt.js

Nuxt.js (bazuar në Vue) ka modelet e veta. Në Nuxt 3, përdorni composable useHead ose konfigurimin e app head në nuxt.config.ts për të shtuar CMP script globalisht. Nuxt mbështet një opsion body: false (që i vendos skriptet në head) dhe një atribut async për ngarkim jo-bllokues.

Për modalitetin server-side rendering të Nuxt, vlen i njëjti parim: CMP script duhet të jetë në përgjigjen fillestare HTML, jo të injektohet në mënyrë dinamike nga një komponent Vue pas mount.

Shmangia e zhvendosjes së layout-it

Banerët e consent janë famëkeq për shkaktimin e Cumulative Layout Shift (CLS), një Core Web Vital që ndikon në renditjen SEO. Kur një baner shfaqet pasi faqja është renderuar, ai shtyn përmbajtjen poshtë ose e mbivendos atë në mënyrë të papritur.

Strategji për të minimizuar CLS nga banerët e consent:

Përdorni një baner të pozicionuar në fund: Banerët në fund të viewport-it nuk e zhvendosin përmbajtjen e faqes. Kjo është qasja më miqësore për CLS.
Rezervoni hapësirë: Nëse duhet të përdorni një baner në krye, rezervoni hapësirën vertikale në CSS në mënyrë që layout-i i faqes ta marrë parasysh banerin përpara se të renderohet.
Shmangni modal overlays në ngarkim: Muret e consent me ekran të plotë që shfaqen pasi faqja është renderuar shkaktojnë paqëndrueshmëri të perceptuar të layout-it. Nëse keni nevojë për një mur, renderojeni si pjesë të gjendjes fillestare të faqes.
Ngarkoni CMP në mënyrë sinkrone në head: Kur CMP ngarkohet si script q�� bllokon renderimin në head, baneri mund të shfaqet si pjesë e pikturës fillestare në vend që të shfaqet më vonë.

Qasja agnostike ndaj kuadrit e FlexyConsent

FlexyConsent është projektuar të funksionojë me çdo kuadër — ose pa asnjë kuadër — duke operuar në nivel script-i dhe jo në nivel komponenti. Ja pse kjo ka rëndësi:

Një tag i vetëm script async: Mjafton një tag <script> në <head>. Asnjë paketë npm për t’u instaluar, asnjë wrapper specifik për kuadrin, asnjë konfigurim ndërtimi.
Vlerat e parazgjedhura të consent ekzekutohen menjëherë: Script-i vendos vlerat e parazgjedhura të Consent Mode V2 si veprimin e tij të parë, përpara çdo callback-u ose manipulimi të DOM. Kjo do të thotë që tag-et e Google respektojnë consent që në milisekondën e parë.
Pa varësi nga DOM: Logjika e consent nuk pret që React, Vue ose Svelte të hidratohet. Ajo funksionon në mënyrë të pavarur nga cikli jetësor i kuadrit.
Funksionon me SSG, SSR, ISR dhe CSR: Meqenëse është një script i thjeshtë, funksionon në mënyrë identike pavarësisht nëse faqja është gjeneruar statikisht, është renderuar në server, është rigjeneruar në mënyrë inkrementale ose është renderuar në anën e klientit.

Këshillë për zhvilluesit: Testi më i thjeshtë për integrim të saktë të CMP është të hapni Network tab në shfletues, të filtroni sipas domain-eve të Google dhe të ringarkoni faqen. Asnjë kërkesë drejt Google nuk duhet të ekzekutohet përpara se komanda e vlerave të parazgjedhura të consent të shfaqet në console. Nëse ndodh, CMP juaj po ngarkohet shumë vonë.

Plani falas i FlexyConsent mbështet pageviews të pakufizuara dhe funksionon me Next.js, Gatsby, Nuxt, Astro, SvelteKit, Remix dhe HTML të thjeshtë. Integrimi është i njëjtë në të gjitha: një script tag, i vendosur siç duhet.