Návod1. června 2026 | FlexyConsent

Souhlas s cookies pro Next.js, Gatsby a statické weby: Průvodce integrací pro vývojáře

Problém souhlasu u statických webů

Moderní JavaScriptové frameworky jako Next.js, Gatsby a Nuxt.js přinesly zásadní změnu v tom, jak se webové stránky vytvářejí a doručují. Stránky se předrenderují v době sestavení nebo na serveru a poté se na klientovi hydratují. To vytváří jedinečnou výzvu pro souhlas s cookies: banner souhlasu musí být připraven dříve, než se spustí jakékoli sledovací skripty, ale samotná stránka už může být vyrenderovaná a uložená v cache na hraně.

Tradiční CMP byly navrženy pro serverově renderované PHP nebo jednoduché HTML stránky, kde se dokument načítá lineárně shora dolů. Ve světě frameworků s dělením kódu, líným načítáním a streamovaným serverovým renderováním se tyto předpoklady hroutí. Správné zajištění souhlasu v těchto prostředích vyžaduje pochopení renderovacího pipeline.

Proč je načasování důležitější, než si myslíte

Na standardní HTML stránce je umístění CMP skriptu do <head> před ostatní skripty jednoduché. V Next.js App Routeru nebo Gatsby je situace složitější:

Předrenderované HTML přichází první: Prohlížeč obdrží kompletní HTML z CDN nebo serveru. Pokud jsou v tomto HTML vloženy jakékoli inline skripty nebo tagy třetích stran, mohou se spustit dříve, než se načte vaše logika souhlasu.
Mezera v hydrataci: Hydratace Reactu probíhá po vykreslení HTML. Pokud je vaše komponenta souhlasu React komponentou, neexistuje ve funkčním stavu, dokud se hydratace nedokončí. Během této mezery se mohou Google tagy nebo analytické skripty spustit bez souhlasu.
Komplikace s cache na hraně: Pokud používáte ISR (Inkrementální statickou regeneraci) nebo edge funkce, HTML je uložené v cache. Nemůžete dynamicky injektovat logiku závislou na souhlasu do cachovaného HTML bez mechanismu na straně klienta.

Základní princip je tento: souhlas musí být stanoven na úrovni skriptu, nikoli na úrovni komponenty. React komponenta, která renderuje banner souhlasu, je příliš pozdě, pokud se stane interaktivní až po hydrataci.

Integrace s Next.js App Router

Next.js 13+ s App Routerem zavedl nový způsob práce se skripty. Zde je doporučený přístup pro integraci souhlasu:

Krok 1: Načtěte CMP skript v kořenovém Layoutu

Použijte komponentu Script Next.js se strategií beforeInteractive ve vašem kořenovém layout.tsx. To říká Next.js, aby injektoval skript do počátečního HTML dokumentu, před zahájením hydratace:

Strategie beforeInteractive je klíčová. Výchozí strategie afterInteractive načítá skripty po hydrataci, což je pro souhlas příliš pozdě. S beforeInteractive je CMP skript zahrnut v serverově renderovaném HTML a spouští se při načítání stránky.

Krok 2: Nastavte výchozí souhlas před Google tagy

Před váš Google Tag Manager nebo gtag.js snippet zahrňte inline skript, který nastaví výchozí stavy souhlasu. To zajistí, že i když se GTM načte před zobrazením CMP banneru, bude respektovat zamítnuté výchozí hodnoty:

Tento inline skript by měl být umístěn v <head> vašeho kořenového layoutu, před CMP a GTM skripty. V Next.js můžete pro tento účel použít běžný tag <script> uvnitř elementu <head> vašeho layoutu.

Krok 3: Zpracování změn trasy

Při navigaci v jednostránkové aplikaci se CMP skript načte jednou, ale změny trasy nevyvolávají úplné znovunačtení stránky. Vaše CMP musí přetrvávat přes navigace na straně klienta. FlexyConsent to zpracovává automaticky — jakmile je načten, zůstává aktivní přes všechny změny trasy bez opětovné inicializace.

Integrace s Next.js Pages Router

Pro projekty, které stále používají Pages Router, je přístup podobný, ale používá _document.tsx místo kořenového layoutu. Umístěte CMP skript do komponenty <Head> vaší vlastní třídy Document. Strategie beforeInteractive funguje stejným způsobem v Pages Routeru.

Klíčový rozdíl je v tom, že _document.tsx se renderuje pouze na serveru, takže jakákoli logika souhlasu zde má zaručeno, že bude v počátečním HTML payloadu.

Integrace statického webu s Gatsby

Gatsby generuje plně statické HTML v době sestavení. V době požadavku neprobíhá žádné serverové renderování, což zjednodušuje některé aspekty, ale komplikuje jiné:

Použijte gatsby-ssr.tsx pro injektování CMP skriptu do <head> každé stránky. API onRenderBody vám umožňuje přidávat skripty do hlavičky, které budou přítomny v každém statickém HTML souboru.
Vyhněte se Gatsby pluginům, které líně načítají souhlas: Některé komunitní pluginy obalují souhlas do React komponent, které se připojí až po hydrataci. To vytváří dříve diskutovanou časovou mezeru.
Umístěte výchozí hodnoty souhlasu inline: Použijte setHeadComponents v gatsby-ssr.tsx pro přidání inline skriptu nastavujícího výchozí stavy souhlasu. Tento skript bude ve statickém HTML a spustí se okamžitě.

Přístup Gatsby v době sestavení znamená, že každý HTML soubor na vašem CDN bude obsahovat skript souhlasu. To je vlastně ideální — neexistuje žádná serverová logika, která by mohla selhat nebo být nesprávně cachovaná.

Úvahy o Nuxt.js

Nuxt.js (založený na Vue) má své vlastní vzory. V Nuxt 3 použijte composable useHead nebo konfiguraci hlavičky aplikace v nuxt.config.ts pro globální přidání CMP skriptu. Nuxt podporuje volbu body: false (která umísťuje skripty do hlavičky) a atribut async pro neblokující načítání.

Pro režim serverového renderování Nuxt platí stejný princip: CMP skript musí být v počáteční HTML odpovědi, ne dynamicky injektován Vue komponentou po připojení.

Vyhýbání se posunu rozvržení

Bannery souhlasu jsou proslulé tím, že způsobují Kumulativní posun rozvržení (CLS), Core Web Vital metriku, která ovlivňuje SEO hodnocení. Když se banner objeví po vyrenderování stránky, posune obsah dolů nebo ho neočekávaně překryje.

Strategie pro minimalizaci CLS z bannerů souhlasu:

Použijte banner umístěný dole: Bannery ve spodní části viewportu neposouvají obsah stránky. To je přístup nejvíce příznivý pro CLS.
Rezervujte prostor: Pokud musíte použít horní banner, rezervujte vertikální prostor ve vašem CSS, aby rozvržení stránky počítalo s bannerem před jeho vyrenderováním.
Vyhněte se modálním překryvům při načítání: Celostránkové stěny souhlasu, které se objeví po vyrenderování stránky, způsobují vnímanou nestabilitu rozvržení. Pokud potřebujete stěnu, vyrenderujte ji jako součást počátečního stavu stránky.
Načtěte CMP synchronně v hlavičce: Když je CMP načtena jako render-blokující skript v hlavičce, banner se může objevit jako součást počátečního vykreslení místo pozdějšího vyskočení.

Frameworkově nezávislý přístup FlexyConsent

FlexyConsent byl navržen tak, aby fungoval s jakýmkoli frameworkem — nebo bez jakéhokoli frameworku — tím, že operuje na úrovni skriptu místo úrovně komponenty. Zde je důvod, proč na tom záleží:

Jeden asynchronní skriptový tag: Jeden tag <script> v <head> je vše, co je potřeba. Žádné npm balíčky k instalaci, žádné frameworkově specifické obálky, žádná konfigurace sestavení.
Výchozí hodnoty souhlasu se spustí okamžitě: Skript nastaví výchozí hodnoty Consent Mode V2 jako svou první akci, před jakýmkoli callbackem nebo manipulací s DOM. To znamená, že Google tagy respektují souhlas od první milisekundy.
Žádná závislost na DOM: Logika souhlasu nečeká na hydrataci Reactu, Vue nebo Svelte. Operuje nezávisle na životním cyklu frameworku.
Funguje s SSG, SSR, ISR a CSR: Protože je to prostý skript, funguje identicky bez ohledu na to, zda byla stránka staticky vygenerována, serverově renderována, inkrementálně regenerována nebo klientsky renderována.

Tip pro vývojáře: Nejjednodušší test správné CMP integrace je otevřít záložku Network v prohlížeči, filtrovat podle Google domén a znovu načíst stránku. Žádné Google požadavky by se neměly spustit předtím, než se v konzoli objeví příkaz výchozího souhlasu. Pokud se spustí, vaše CMP se načítá příliš pozdě.

Bezplatný plán FlexyConsent podporuje neomezený počet zobrazení stránek a funguje s Next.js, Gatsby, Nuxt, Astro, SvelteKit, Remix a obyčejným HTML. Integrace je stejná napříč všemi: jeden skriptový tag, správně umístěný.