Dokumentace

Vše, co potřebujete vědět pro rychlou implementaci Consentio

Vlastní web

Pokročilá implementace Consentio pro vývojáře

Základní implementace

Pro základní implementaci stačí vložit jeden řádek kódu hned za otevírací tag <head>, před všechny Google tagy:

HTML
<script src="https://consentio.cz/widget/YOUR_SCRIPT_KEY/consentio.min.js" async></script>

Widget se automaticky inicializuje a zobrazí cookie lištu při prvním načtení stránky. Kód s vaším unikátním SCRIPT_KEY najdete v dashboardu v sekci Moje weby → váš web → Instalace.

Tip: Identifikace webu je součástí URL (SCRIPT_KEY), žádné další data atributy nejsou potřeba. Jazyk lišty se řídí atributem lang na elementu <html>, a to v rámci jazyků, které máte zapnuté (viz Jazyky).

JavaScript API

Po načtení widgetu je dostupný globální objekt window.Consentio pro programatické ovládání. Widget se načítá asynchronně, takže kód, který běží při načítání stránky, nemůže počítat s tím, že objekt už existuje. Jak na něj počkat, ukazují příklady níže.

Dostupné metody

Metoda Popis
show() Zobrazí cookie banner
hide() Skryje cookie banner
showPreferences() Zobrazí nastavení preferencí
getConsent() Vrátí volbu návštěvníka, nebo null, dokud si návštěvník nevybral
updateConsent(updates) Změní volbu, kterou už návštěvník udělal. Před první volbou neudělá nic; při odvolání kategorie stránku znovu načte
onConsentChange(callback) Zavolá callback po každé volbě a jednou při každém načtení stránky, pokud je volba už uložená. Callback zaregistrovaný později se zavolá jednou s aktuální volbou
getBlockedScripts() Vrátí objekt s počtem dosud zadržených skriptů v každé kategorii (označených i zadržených automaticky), např. { marketing: 2 }
getBlockedIframes() Vrátí stejný objekt pro označené iframe

Zobrazení lišty

JavaScript
// Volejte až po načtení widgetu, například z obsluhy kliknutí.
// Zápis window.Consentio?. volání přeskočí, pokud widget ještě není načtený.

// Zobrazit cookie lištu
window.Consentio?.show()

// Skrýt cookie lištu
window.Consentio?.hide()

// Zobrazit nastavení preferencí
window.Consentio?.showPreferences()

Získání stavu souhlasů

JavaScript
// Volba návštěvníka, nebo null, dokud si nevybral
const consent = window.Consentio?.getConsent()
// { necessary: true, functionality: false, analytics: false, marketing: false }

// Před čtením kategorie vždy počítejte s hodnotou null
if (consent?.analytics) {
  // Analytika je povolená
}

if (consent?.marketing) {
  // Marketing je povolený
}

// Skript, který má čekat na souhlas, načítejte přes onConsentChange (níže)

Aktualizace souhlasů

JavaScript
// Změní volbu, kterou už návštěvník udělal; před první volbou neudělá nic.
// Volejte jen z akce samotného návštěvníka (například z vlastního přepínače):
// zaznamená se jako jeho volba.
window.Consentio?.updateConsent({
  analytics: true,
  marketing: false
})
// Vypnutí kategorie, která byla zapnutá, stránku znovu načte

Event listenery

Obě možnosti se spustí po každé volbě a jednou při každém načtení stránky, pokud je volba už uložená. Na jedné stránce se mohou spustit víckrát, proto skript načítejte jen jednou a nikdy z nich stránku znovu nenačítejte.

JavaScript
// Možnost 1: onConsentChange. Funguje z jakéhokoli kódu, i z toho, který běží později
// (bundle, hook frameworku): callback zaregistrovaný později se zavolá jednou
// s aktuální volbou. Widget se načítá asynchronně, proto na něj počkejte:
function onConsent(callback) {
  if (window.Consentio) {
    Consentio.onConsentChange(callback)
  } else {
    window.addEventListener('consentio:consent', (event) => callback(event.detail))
  }
}

let analyticsLoaded = false
onConsent((consent) => {
  if (consent.analytics && !analyticsLoaded) {
    analyticsLoaded = true
    loadGoogleAnalytics()
  }
})

// Možnost 2: událost na window. Neopakuje se, proto listener zaregistrujte
// v inline skriptu přímo v HTML stránky, dřív než se stránka dočte.
window.addEventListener('consentio:consent', (event) => {
  const consent = event.detail
  console.log('Souhlas:', consent)
})

Google Consent Mode v2

Consentio posílá signály Google Consent Mode v2 za vás. Jedinou podmínkou je, aby byl jeho kód na stránce před Google Analytics a dalšími Google tagy: jeho první část nastaví vše na „zamítnuto“ dřív, než si to Google přečte.

Basic, nebo Advanced?

Consentio posílá Googlu signály souhlasu na všech plánech. V jakém režimu vaše Google skripty běží, určuje způsob jejich vložení na web:

  • Advanced (standardní instalace, ukázka níže) — gtag.js se načte hned a před souhlasem posílá Googlu anonymní pingy bez cookies, ze kterých GA4 modeluje konverze. Z pohledu ePrivacy jde o šedou zónu: data odcházejí ještě před souhlasem.
  • Basic (blokovaný skript) — gtag.js vložíte jako <script type="text/plain" data-category="analytics">. Načte se až po souhlasu a Google před ním nedostane nic. Nejbezpečnější varianta, přicházíte jen o modelovaná data.

Doporučujeme Basic. Advanced zvolte vědomě, pokud modelovaná data v GA4 a Google Ads opravdu potřebujete.

HTML
<!-- 1. Nejprve kód Consentio, nad všemi Google tagy (bez async) -->
<script src="https://consentio.cz/widget/YOUR_SCRIPT_KEY/consentio.min.js"></script>

<!-- 2. Pak Google tag -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'G-XXXXXXX');
</script>

Mapování kategorií na Consent Mode

Consentio kategorie Google Consent Mode
necessary žádný (security_storage je vždy povolen)
analytics analytics_storage
marketing ad_storage, ad_user_data, ad_personalization
functionality functionality_storage, personalization_storage

Automatické blokování známých služeb

Skripty známých měřicích a reklamních služeb Consentio pozná podle adresy a zadrží je samo, dokud návštěvník nepovolí jejich kategorii. V kódu webu nemusíte nic měnit. Platí to i pro skripty, které na stránku později přidá správce značek nebo jiný kód.

  • Analytické: Hotjar, Microsoft Clarity, Smartlook, Mouseflow, FullStory, Mixpanel, Amplitude, Heap, Segment, Crazy Egg, Lucky Orange, Yandex Metrica
  • Marketingové: Meta Pixel, TikTok Pixel, LinkedIn Insight Tag, Microsoft Advertising (UET), Pinterest Tag, X (Twitter) Pixel, Snapchat Pixel, Reddit Pixel, Quora Pixel, Criteo, Taboola, Outbrain, AdRoll, Adform, RTB House, HubSpot, Klaviyo, Mailchimp, Sklik, Heureka (měření konverzí), Glami Pixel, Leady

Google tagy (Google Analytics, Google Ads, Tag Manager) se neblokují: zůstávají načtené a řídí se signály Consent Mode. Chat, vložená videa a mapy Consentio samo nezadrží, protože by to změnilo, co návštěvník na stránce vidí; ty označte ručně podle návodu níže.

Kdy automatika nestačí: zadržet jde jen skript, který se ještě nespustil. Kód Consentio se načítá asynchronně, takže při úplně první návštěvě se skript vložený přímo do stránky může spustit dřív, než Consentio dorazí. Jeho cookies pak Consentio smaže, ale první zobrazení stránky už služba zaznamenala. Od druhé stránky má prohlížeč kód Consentio zpravidla uložený a spouští ho jako první. Jistotu už od první stránky dává ruční označení skriptu (níže), nebo kód Consentio vložený bez async jako první skript v <head>.

Výjimka pro jednu službu: přidejte jejímu tagu data-category="necessary" a Consentio ji nechá běžet. Vypnutí pro celý web: v dashboardu v Designeru, sekce Chování, přepínač „Automaticky blokovat známé měřicí a reklamní skripty“.

Blokování skriptů

Pro blokování skriptů před udělením souhlasu použijte atribut type="text/plain" s datovým atributem data-category:

HTML
<!-- Skript se spustí až po udělení souhlasu s analytics -->
<script type="text/plain" data-category="analytics">
  // Google Analytics kód
  gtag('config', 'G-XXXXXXX');
</script>

<!-- Skript se spustí až po udělení souhlasu s marketing -->
<script type="text/plain" data-category="marketing">
  // Facebook Pixel kód
  fbq('init', 'XXXXXXX');
</script>

<!-- Skript se spustí až po udělení souhlasu s functionality -->
<script type="text/plain" data-category="functionality">
  // Personalizační kód
  initPersonalization();
</script>

Dostupné kategorie

Kategorie Popis
necessary Nezbytné cookies (vždy povoleny)
analytics Analytické cookies
marketing Marketingové cookies
functionality Funkční cookies pro personalizaci

Tlačítko pro otevření preferencí

Plovoucí tlačítko pro změnu volby se zobrazuje vždy. Navíc můžete přidat vlastní odkaz nebo tlačítko, které preference otevře:

HTML
<!-- V patičce webu -->
<a href="#" onclick="Consentio.showPreferences(); return false;">
  Nastavení cookies
</a>

<!-- Nebo jako button -->
<button onclick="Consentio.showPreferences()">
  Upravit preference cookies
</button>
Tip: Návštěvník musí mít možnost svou volbu kdykoli změnit nebo odvolat. To zajišťuje plovoucí tlačítko; s odkazem v patičce nebo v zásadách ochrany osobních údajů ji najde snáz.

Single Page Applications (SPA)

Widget funguje i v Reactu, Vue, Angularu a dalších SPA frameworcích. Zachytí změnu URL, znovu pošle Googlu stav souhlasu a spustí nově přidané označené skripty, jejichž kategorie je povolená.

JavaScript
// Příklad: Kontrola stavu souhlasů při změně route (Vue Router)
router.afterEach(() => {
  // null, dokud si návštěvník nevybral
  const consent = window.Consentio?.getConsent()
  if (consent?.analytics) {
    // Analytické skripty jsou povoleny
  }
})
ShoptetGoogle Tag Manager