Dərslik1 iyun 2026 | FlexyConsent

Next.js, Gatsby və Statik Saytlar üçün Kuki Razılığı: Tərtibatçının İnteqrasiya Bələdçisi

Statik Sayt Razılıq Problemi

Next.js, Gatsby və Nuxt.js kimi müasir JavaScript çərçivələri veb səhifələrin necə qurulduğu və təqdim edildiyi sahəsində paradiqma dəyişikliyi yaratdı. Səhifələr qurma zamanı və ya serverdə əvvəlcədən render edilir, sonra isə müştəri tərəfində hidratlaşdırılır. Bu, kuki razılığı üçün unikal bir problem yaradır: razılıq bannerı hər hansı izləmə skriptləri icra olunmadan əvvəl hazır olmalıdır, lakin səhifənin özü artıq render edilmiş və kənar serverdə keşlənmiş ola bilər.

Ənənəvi CMP-lər sənədin yuxarıdan aşağıya doğru xətti şəkildə yükləndiyi server tərəfindən render edilən PHP və ya sadə HTML səhifələr üçün hazırlanmışdı. Kod bölünməsi, tənbəl yükləmə və axın edən server tərəfi renderinqi olan çərçivə dünyasında bu fərziyyələr pozulur. Bu mühitlərdə razılığı düzgün əldə etmək render boru kəmərini anlamağı tələb edir.

Niyə Zamanlama Düşündüyünüzdən Daha Vacibdir

Standart HTML səhifəsində CMP skriptini digər skriptlərdən əvvəl <head> bölməsinə yerləşdirmək sadədir. Next.js App Router və ya Gatsby-də vəziyyət daha mürəkkəbdir:

Əvvəlcədən render edilmiş HTML birinci gəlir: Brauzer CDN və ya serverdən tam HTML alır. Əgər həmin HTML-ə hər hansı daxili skriptlər və ya üçüncü tərəf etiketləri daxil edilibsə, onlar razılıq məntiqi yüklənmədən əvvəl icra oluna bilər.
Hidratasiya boşluğu: React hidratasiyası HTML çəkildikdən sonra baş verir. Əgər razılıq komponentiniz React komponentidirsə, hidratasiya tamamlanana qədər funksional vəziyyətdə mövcud deyil. Bu boşluq ərzində Google etiketləri və ya analitika skriptləri razılıq olmadan işə düşə bilər.
Kənar keşləmə çətinlikləri: ISR (Artımlı Statik Regenerasiya) və ya kənar funksiyalar istifadə edirsinizsə, HTML keşlənir. Müştəri tərəfi mexanizmi olmadan keşlənmiş HTML-ə razılıqdan asılı məntiqi dinamik olaraq daxil edə bilməzsiniz.

Əsas prinsip budur: razılıq komponent səviyyəsində deyil, skript səviyyəsində müəyyən edilməlidir. Razılıq bannerı göstərən React komponenti, yalnız hidratasiyadan sonra interaktiv olursa, çox gecdir.

Next.js App Router İnteqrasiyası

App Router ilə Next.js 13+ skriptlərlə işləmək üçün yeni yol təqdim etdi. Razılıq inteqrasiyası üçün tövsiyə olunan yanaşma budur:

Addım 1: CMP Skriptini Kök Layoutda Yükləyin

Kök layout.tsx faylınızda beforeInteractive strategiyası ilə Next.js Script komponentindən istifadə edin. Bu, Next.js-ə skripti ilkin HTML sənədinə hidratasiya başlamazdan əvvəl daxil etməyi bildirir:

beforeInteractive strategiyası vacibdir. Defolt afterInteractive strategiyası skriptləri hidratasiyadan sonra yükləyir ki, bu da razılıq üçün çox gecdir. beforeInteractive ilə CMP skripti server tərəfindən render edilmiş HTML-ə daxil edilir və səhifə yüklənərkən icra olunur.

Addım 2: Google Etiketlərindən Əvvəl Defolt Razılığı Təyin Edin

Google Tag Manager və ya gtag.js snippet-inizdən əvvəl defolt razılıq vəziyyətlərini təyin edən daxili skript daxil edin. Bu, GTM CMP bannerı görünmədən əvvəl yüklənsə belə, rədd edilmiş defoltlara hörmət etməsini təmin edir:

Bu daxili skript kök layoutunuzun <head> bölməsində, CMP və GTM skriptlərindən əvvəl yerləşdirilməlidir. Next.js-də bu məqsəd üçün layoutunuzun <head> elementinin içərisində adi <script> etiketindən istifadə edə bilərsiniz.

Addım 3: Marşrut Dəyişikliklərini İdarə Edin

Tək səhifəli tətbiq naviqasiyasında CMP skripti bir dəfə yüklənir, lakin marşrut dəyişiklikləri tam səhifə yenilənməsini işə salmır. CMP-niz müştəri tərəfi naviqasiyaları boyunca davam etməlidir. FlexyConsent bunu avtomatik olaraq idarə edir — bir dəfə yükləndikdən sonra yenidən başlatma olmadan bütün marşrut dəyişikliklərində aktiv qalır.

Next.js Pages Router İnteqrasiyası

Hələ də Pages Router istifadə edən layihələr üçün yanaşma oxşardır, lakin kök layout əvəzinə _document.tsx istifadə edir. CMP skriptini xüsusi Document sinifinizdəki <Head> komponentinə yerləşdirin. beforeInteractive strategiyası Pages Router-da eyni şəkildə işləyir.

Əsas fərq ondadır ki, _document.tsx yalnız serverdə render edilir, buna görə də buradakı hər hansı razılıq məntiqi ilkin HTML yükündə olacağına zəmanət verilir.

Gatsby Statik Sayt İnteqrasiyası

Gatsby qurma zamanı tam statik HTML yaradır. Sorğu zamanı server tərəfi renderinqi yoxdur ki, bu da bəzi aspektləri sadələşdirir, lakin digərlərini çətinləşdirir:

CMP skriptini hər səhifənin <head> bölməsinə daxil etmək üçün gatsby-ssr.tsx istifadə edin. onRenderBody API-si başlığa hər statik HTML faylında mövcud olacaq skriptlər əlavə etməyə imkan verir.
Razılığı tənbəl yükləyən Gatsby plaginlərindən çəkinin: Bəzi icma plaginləri razılığı yalnız hidratasiyadan sonra montaj edilən React komponentlərinə bükür. Bu, daha əvvəl müzakirə etdiyimiz zamanlama boşluğunu yaradır.
Razılıq defoltlarını daxili olaraq yerləşdirin: Defolt razılıq vəziyyətlərini təyin edən daxili skript əlavə etmək üçün gatsby-ssr.tsx-da setHeadComponents istifadə edin. Bu skript statik HTML-də olacaq və dərhal icra olunacaq.

Gatsby-nin qurma zamanı yanaşması o deməkdir ki, CDN-nizdəki hər HTML faylı razılıq skriptini daxil edəcək. Bu əslində idealdır — uğursuz ola biləcək və ya düzgün keşlənməyəcək server məntiqi yoxdur.

Nuxt.js Mülahizələri

Nuxt.js-in (Vue əsaslı) öz nümunələri var. Nuxt 3-də CMP skriptini qlobal olaraq əlavə etmək üçün useHead composable və ya nuxt.config.ts tətbiq başlıq konfiqurasiyasından istifadə edin. Nuxt body: false seçimini (skriptləri başlığa yerləşdirən) və bloklamayan yükləmə üçün async atributunu dəstəkləyir.

Nuxt-un server tərəfi renderinq rejimi üçün eyni prinsip tətbiq olunur: CMP skripti ilkin HTML cavabında olmalıdır, montajdan sonra Vue komponenti tərəfindən dinamik olaraq daxil edilməməlidir.

Layout Sürüşməsinin Qarşısını Almaq

Razılıq bannerləri SEO sıralamasına təsir edən Core Web Vital olan Kumulyativ Layout Sürüşməsinə (CLS) səbəb olmaqla məşhurdur. Banner səhifə render edildikdən sonra görünəndə məzmunu aşağı itələyir və ya gözlənilmədən üst-üstə düşür.

Razılıq bannerlərindən CLS-ni minimuma endirmək üçün strategiyalar:

Aşağıda yerləşən banner istifadə edin: Görünüş sahəsinin altındakı bannerlər səhifə məzmununu sürüşdürmür. Bu, CLS üçün ən uyğun yanaşmadır.
Yer ayırın: Yuxarı banner istifadə etmək məcburiyyətindəsinizsə, CSS-nizdə şaquli yeri ayırın ki, səhifə tərtibatı banner render edilmədən əvvəl onu nəzərə alsın.
Yükləmə zamanı modal örtüklərdən çəkinin: Səhifə render edildikdən sonra görünən tam ekran razılıq divarları hiss olunan layout qeyri-sabitliyi yaradır. Əgər divara ehtiyacınız varsa, onu ilkin səhifə vəziyyətinin bir hissəsi kimi render edin.
CMP-ni başlıqda sinxron olaraq yükləyin: CMP başlıqda render-bloklayan skript kimi yüklənəndə, banner sonradan görünmək əvəzinə ilkin çəkiliş zamanı görünə bilər.

FlexyConsent-in Çərçivədən Asılı Olmayan Yanaşması

FlexyConsent komponent səviyyəsində deyil, skript səviyyəsində işləyərək istənilən çərçivə ilə — və ya heç bir çərçivə olmadan — işləmək üçün hazırlanmışdır. Bunun niyə vacib olduğu budur:

Tək asinxron skript etiketi: <head> bölməsində bir <script> etiketi bütün lazım olandır. Quraşdırılacaq npm paketləri yoxdur, çərçivəyə xas sarğılar yoxdur, qurma konfiqurasiyası yoxdur.
Razılıq defoltları dərhal işə düşür: Skript hər hansı callback və ya DOM manipulyasiyasından əvvəl ilk hərəkəti olaraq Consent Mode V2 defoltlarını təyin edir. Bu, Google etiketlərinin ilk millisekunddan etibarən razılığa hörmət etməsi deməkdir.
DOM-dan asılılıq yoxdur: Razılıq məntiqi React, Vue və ya Svelte-in hidratlaşmasını gözləmir. Çərçivə həyat dövrüsündən asılı olmayaraq işləyir.
SSG, SSR, ISR və CSR ilə işləyir: Adi skript olduğu üçün səhifənin statik olaraq yaradılmasından, server tərəfindən render edilməsindən, artımlı olaraq regenerasiya edilməsindən və ya müştəri tərəfindən render edilməsindən asılı olmayaraq eyni şəkildə işləyir.

Tərtibatçı məsləhəti: Düzgün CMP inteqrasiyası üçün ən sadə test brauzerinizin Şəbəkə panelini açmaq, Google domenlərinə görə filtrləmək və səhifəni yenidən yükləməkdir. Konsolda defolt razılıq əmri görünmədən əvvəl heç bir Google sorğusu işə düşməməlidir. Əgər düşürsə, CMP-niz çox gec yüklənir.

FlexyConsent-in pulsuz planı limitsiz səhifə baxışlarını dəstəkləyir və Next.js, Gatsby, Nuxt, Astro, SvelteKit, Remix və sadə HTML ilə işləyir. İnteqrasiya hamısında eynidir: bir skript etiketi, düzgün yerləşdirilmiş.