DOKUMENTATION

Installation mit einer Zeile, unbegrenzte Anpassung

Starten Sie mit einer einzigen Codezeile. HTML, WordPress, Shopify, Next.js oder GTM: eine Schritt-für-Schritt-Anleitung für jede Plattform.

SCHNELLSTART

Ein funktionierendes Banner in 3 Schritten

Folgen Sie den untenstehenden Schritten.

Konto erstellen

14-tägige kostenlose Testphase. Keine Kreditkarte erforderlich; Sie registrieren sich mit Ihrer E-Mail-Adresse.

Domain hinzufügen

Geben Sie Ihre Domain-URL im Admin-Panel > Domains ein. Ein API Key und ein Secret Key werden automatisch erstellt.

Code einfügen

Fügen Sie den einzeiligen Installationscode als erste Zeile in das <head>-Tag Ihrer Website ein. Banner und Widget werden automatisch geladen.

EMBED-CODE

Eine Zeile, zwei Produkte

Fügen Sie den untenstehenden Code direkt nach dem öffnenden <head>-Tag Ihrer Website ein, vor allen anderen Skripten. Den Wert für data-cerez-key erhalten Sie im Admin-Panel > Installation. 

<!-- cerez.io Cookie Consent + Accessibility -->
<script src="https://cerez.io/sdk/loader.js"
        data-cerez-key="YOUR_API_KEY"></script>
Wichtig Fügen Sie kein async oder defer hinzu. Der kleine Loader muss vor allen anderen Skripten laufen: Er schreibt den Google-Consent-Mode-Standard als Erstes und hält bekannte, per JavaScript eingefügte Tracker bis zur Einwilligung zurück. Den Banner- und Widget-Code lädt er selbst asynchron. Die Konfiguration wird 5 Minuten serverseitig zwischengespeichert; das SDK übernimmt Ihre Änderungen beim nächsten Laden.
NPM-PAKET

Installation mit npm

Das Paket @cerez-io/sdk ist für Entwickler, die Apps mit React, Next.js oder Vue bauen und die Einrichtung in ihrem eigenen Code verwalten möchten. Das Paket führt denselben Code aus wie das Installations-Tag: Es schreibt den Consent-Mode-Standard, hält per JavaScript eingefügte bekannte Tracker bis zur Einwilligung zurück und lädt den Banner mit Ihren Panel-Einstellungen.

Wichtig Der empfohlene Weg, Tracker beim Laden der Seite zu blockieren, ist das Installations-Tag im <head>; das npm-Paket ersetzt es nicht. Das Paket läuft erst, nachdem Ihr App-Code geladen ist, und kann Tracker, die im HTML stehen oder vorher laufen, nicht stoppen. Markieren Sie diese Tags mit type="text/plain" und data-cb-category. Verwenden Sie das Paket nicht zusammen mit dem Installations-Tag: Auf der Seite darf nur eines von beiden stehen.

1. Paket installieren

npm install @cerez-io/sdk

2. Am Einstiegspunkt der App initialisieren

Rufen Sie init vor jedem anderen Tracker-Code auf (Google Analytics, Meta Pixel, GTM). Ersetzen Sie YOUR_SITE_KEY durch den Website-Schlüssel von der Installationsseite im Panel.

import { init, on, hasConsent } from '@cerez-io/sdk';

init({ key: 'YOUR_SITE_KEY' });

on('consent', () => {
  if (hasConsent('analytics')) {
    startAnalytics();
  }
});

3. Navigation in einer Single-Page-App

Rufen Sie nach clientseitiger Navigation page() auf; der erste Ladevorgang wird automatisch gezählt. Das Beispiel gilt für Vue Router.

import { page } from '@cerez-io/sdk';

router.afterEach(() => page());

Next.js

init muss im Browser laufen; auf dem Server aufgerufen, tut es nichts. Fügen Sie die Komponente einmal im Root-Layout ein.

'use client';

import { useEffect } from 'react';
import { init } from '@cerez-io/sdk';

export default function CerezIo() {
  useEffect(() => {
    init({ key: 'YOUR_SITE_KEY' });
  }, []);

  return null;
}

Weitere Funktionen: getConsent(), hasConsent(kategorie), showBanner(), on('consent', fn). Die Optionen (host, lang, autoBlock, nonce, userId) sind auf der npm-Seite des Pakets beschrieben.

PLATTFORMEN

Fertige Anleitungen für 6 Plattformen

Für jede Plattform steht eine detaillierte Schritt-für-Schritt-Installationsanleitung zur Verfügung.

HTML / Statische Website

Fügen Sie es als erste Zeile in das <head>-Tag ein. Die Einrichtung dauert 30 Sekunden.

<head>
  <script src="https://cerez.io/sdk/loader.js"
          data-cerez-key="YOUR_KEY"></script>
  <!-- mevcut etiketler -->
</head>

WordPress

Laden Sie die WP-Plugin-ZIP herunter, installieren Sie das Plugin, geben Sie den API Key ein.

# Seçenek A: Plugin ile (önerilen)
Admin Panel > Eklentiler > Yeni Ekle
ZIP yükle > Etkinleştir > API Key gir

# Seçenek B: Manuel (functions.php)
add_action('wp_head', function() {
  echo '<script src="https://cerez.io/sdk/loader.js"
  data-cerez-key="YOUR_KEY"></script>';
}, PHP_INT_MIN);

Shopify

Fügen Sie es in theme.liquid ein oder verwenden Sie einen Custom Code Injector.

<!-- theme.liquid içinde, <head> etiketinin hemen altına -->
<script
  src="https://cerez.io/sdk/loader.js"
  data-cerez-key="YOUR_KEY"></script>

Next.js / React

Verwenden Sie ein einfaches <script> als erstes Element im <head> des Root-Layouts; die Strategien von next/script laden das Skript zu spät.

// app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <script
          src="https://cerez.io/sdk/loader.js"
          data-cerez-key="YOUR_KEY"
        />
      </head>
      <body>{children}</body>
    </html>
  )
}

Google Tag Manager

Erstellen Sie ein Custom-HTML-Tag und veröffentlichen Sie es mit dem Trigger Consent Initialization - All Pages. Über GTM installierter Code läuft erst, nachdem GTM geladen wurde; er kann den GTM-Container und direkt in die Seite geschriebene Tags vor der Einwilligung nicht stoppen. Fügen Sie den Code nach Möglichkeit direkt in den Head-Tag ein.

<!-- GTM > Tags > New > Custom HTML -->
<script
  src="https://cerez.io/sdk/loader.js"
  data-cerez-key="YOUR_KEY"></script>

<!-- Trigger: Consent Initialization - All Pages -->

Webflow

Fügen Sie es ganz oben unter Site Settings > Custom Code > Head Code ein.

<!-- Site Settings > Custom Code > Head Code -->
<script
  src="https://cerez.io/sdk/loader.js"
  data-cerez-key="YOUR_KEY"></script>
JAVASCRIPT API

Programmatische Steuerung: 5 Kernmethoden

Sie können das Banner aus Ihrer eigenen Oberfläche öffnen, den Consent prüfen und Events abonnieren. Alle Methoden befinden sich im Namespace window.cerez.io.

CerezBanner.show()

Zeigt das Banner manuell an. Es kann von benutzerdefinierten Auslösern aufgerufen werden, etwa von einem Button "Meine Cookie-Einstellungen verwalten".

// Footer'daki "Çerez Tercihlerim" linkine event listener
document.querySelector('#cookie-prefs').addEventListener('click', () => {
    CerezBanner.show();
});
CerezBanner.getConsent()

Gibt den aktuellen Consent-Status des Nutzers zurück. Wenn noch keine Entscheidung getroffen wurde, wird null zurückgegeben.

const consent = CerezBanner.getConsent();
// Örnek dönüş:
// { necessary: true, analytics: true, marketing: false, functional: true, timestamp: 1717000000 }

if (consent?.analytics) {
    // Google Analytics'i yükle
}
CerezBanner.on(event, callback)

Abonnieren Sie Consent-Änderungen. Unterstützte Events: consent.given, consent.updated, consent.rejected, banner.shown. 

CerezBanner.on('consent.given', (data) => {
    console.log('Onay verildi:', data.categories);

    if (data.categories.marketing) {
        // Facebook Pixel başlat
        fbq('init', 'YOUR_PIXEL_ID');
    }
});
CerezBanner.reset()

Löscht den aktuellen Consent und zeigt das Banner erneut an. Geeignet für Funktionen wie "Meine Einstellungen zurücksetzen".

CerezBanner.reset(); // cb_consent cookie silinir, banner yeniden açılır
CerezBanner.hide()

Blendet das Banner programmatisch aus. Es wird kein Consent gespeichert; nur die Sichtbarkeit ändert sich.

CerezBanner.hide(); // Banner DOM'dan kaldırılmaz, gizlenir
SCRIPT BLOCKING

Skripte von Drittanbietern vor der Einwilligung blockieren

Skripte wie GA4, Facebook Pixel und Hotjar dürfen erst nach erteilter Einwilligung ausgeführt werden (eine KVKK/GDPR-Anforderung). Der Installationscode hält Tags bekannter Anbieter, die per JavaScript eingefügt werden (etwa die Snippets von GTM und Meta Pixel), automatisch bis zur Einwilligung zurück. Direkt in die Seite geschriebene Skript-Tags (<script src>) lädt der Browser herunter, bevor irgendein Code läuft; markieren Sie sie mit den Attributen type="text/plain" und data-cb-category.

Nicht konform (das Skript läuft sofort)

<!-- YANLIŞ: script anında yüklenir -->
<script
  src="https://www.googletagmanager.com/gtag/js?id=G-XXX"
></script>

Konform (läuft nach der Einwilligung)

<!-- DOĞRU: sadece onay sonrası yüklenir -->
<script
  type="text/plain"
  src="https://www.googletagmanager.com/gtag/js?id=G-XXX"
  data-cb-category="analytics"
></script>

Inline-Script-Blockierung

<!-- Inline script için: type="text/plain" + data-cb-category -->
<script type="text/plain" data-cb-category="marketing">
    fbq('init', 'PIXEL_ID');
    fbq('track', 'PageView');
</script>
Unterstützte Kategorien necessary (nicht blockierbar), analytics, marketing, functional

Eingebettete Inhalte (iframe) blockieren

Schreiben Sie bei YouTube-, Vimeo-, Google-Maps- und Social-Media-Einbettungen data-cb-src statt src und geben Sie die Kategorie mit data-cb-category an. Der Inhalt lädt erst nach der Einwilligung; an seiner Stelle erscheint ein gleich großer Platzhalter mit den Schaltflächen „Erlauben und anzeigen“ und „Einstellungen“. Nach der Erlaubnis laden alle Einbettungen derselben Kategorie; wird die Einwilligung widerrufen, kehren sie zum Platzhalter zurück. Für YouTube wird die Adresse youtube-nocookie.com empfohlen.

<iframe data-cb-src="https://www.youtube-nocookie.com/embed/VIDEO_ID"
  data-cb-category="marketing" width="560" height="315" title="Video"></iframe>
Grenze Ein nicht gekennzeichnetes iframe, das direkt mit src in die Seite geschrieben ist, kann nicht blockiert werden: der Browser lädt es, bevor der Installationscode läuft. Der Installationscode erfasst nur bekannte, später per JavaScript eingefügte Einbettungen (YouTube, Vimeo, Google Maps, Instagram, X, TikTok, Facebook) nach bestem Bemühen.
GOOGLE CONSENT MODE V2

Automatische Integration, ein einziger Toggle

Aktivieren Sie den Toggle "Consent Mode v2" unter Admin-Panel > Site-Einstellungen > Google-Integration. Das SDK verwaltet automatisch gtag('consent', 'default', {...}) und die Update-Signale.

Das SDK macht dies automatisch

// Sayfa yüklenir yüklenmez, kullanıcı henüz karar vermedi
gtag('consent', 'default', {
    'ad_storage': 'denied',
    'ad_user_data': 'denied',
    'ad_personalization': 'denied',
    'analytics_storage': 'denied',
    'functionality_storage': 'denied',
    'personalization_storage': 'denied',
    'security_storage': 'granted'
});

// Kullanıcı onay verdikten sonra, analytics + marketing kabul edildi
gtag('consent', 'update', {
    'ad_storage': 'granted',
    'analytics_storage': 'granted'
});

Ayrıntılı GCM v2 rehberi için Google Consent Mode v2 sayfasına bakın.

ERWEITERTE EINSTELLUNGEN

Anpassung und Konfiguration

Sie können das Verhalten des SDK anpassen, indem Sie dem Embed-Code zusätzliche Attribute hinzufügen.

Vorschaumodus

Indem Sie ?cb_preview=true an die URL anhängen, können Sie den bestehenden Consent überspringen und das Banner jedes Mal anzeigen. Ideal für Tests und Entwicklung.

Sprachpräferenz

Unter Admin-Panel > Site-Einstellungen > Banner-Sprache können Sie eine feste Sprache wählen oder automatisches Umschalten (auto) anhand der Browsersprache des Besuchers einstellen. TR / EN / DE werden unterstützt.

CSP-Kompatibilität

Wenn Ihre Website eine CSP hat, erlauben Sie https://cerez.io in script-src, connect-src, style-src, font-src und img-src. Mit Nonce überträgt das SDK die Nonce des Tags auf seine eigenen Elemente. Details: CSP-Abschnitt.

sessionStorage Cache

Nach dem Laden speichert das SDK die Banner-Konfiguration in sessionStorage. Innerhalb derselben Sitzung erfolgt kein weiterer Serveraufruf; die Seitenladezeit verkürzt sich.

Consent-Dauer

Legen Sie die Gültigkeitsdauer des cb_consent-Cookies unter Admin-Panel > Site-Einstellungen > Consent-Dauer fest (Standard 180 Tage). Die für die KVKK-Konformität empfohlene Dauer beträgt 6 Monate.

IP-Beschränkung

Beschränken Sie den API-Zugriff, indem Sie den IP-Restriction-Toggle unter Admin-Panel > Installation aktivieren und die erlaubten IP-Adressen eingeben (CIDR-Notation wird unterstützt).

Tastatur und Fokus

Beim Öffnen springt der Fokus auf das Banner selbst, und die Tab-Taste bleibt innerhalb des Banners. Die Esc-Taste wirkt wie "Nur erforderliche". Nach dem Schließen kehrt der Fokus zu dem Element zurück, das das Banner geöffnet hat. Die Schaltflächen Akzeptieren und Ablehnen haben dieselbe Größe und dieselbe Farbe; diese Gleichheit lässt sich nicht deaktivieren.
CONTENT SECURITY POLICY

cerez.io-Domains für die CSP Ihrer Website

Wenn Ihre Website einen Content-Security-Policy-Header sendet, erlauben Sie https://cerez.io in den folgenden Direktiven, damit der Installationscode laufen kann. Die eigenen Domains Ihrer Tracker (Google, Meta usw.) werden zusätzlich benötigt; cerez.io lädt sie erst nach der Einwilligung.

cerez.io-Quellen je Direktive
DirektiveWertWarum
script-srchttps://cerez.ioInstallationscode (loader.js), Cookie-Banner und Dateien des Barrierefreiheits-Tools.
connect-srchttps://cerez.ioBanner-Konfiguration, Einwilligungsprotokoll, Sitzungs- und Nutzungszähler-Anfragen, Sprachpakete; bei aktiver regionaler Regel die Ländercode-Anfrage.
style-srchttps://cerez.ioSchrift-Stylesheet. Banner und Tool fügen ihre Stile mit einem <style>-Element ein: ohne Nonce braucht style-src zusätzlich 'unsafe-inline'.
font-srchttps://cerez.ioSchriften des Banners und des Barrierefreiheits-Tools. Ohne Freigabe laufen beide mit Systemschriften weiter; die Browserkonsole zeigt einen CSP-Fehler.
img-srchttps://cerez.io data:Logo im Banner und im Tool; data: für die Funktion großer Mauszeiger des Barrierefreiheits-Tools.

Richtlinien mit Nonce

Wenn Ihre Richtlinie eine Nonce verwendet (script-src 'nonce-...'), setzen Sie dieselbe Nonce auf das Tag des Installationscodes. Das SDK überträgt sie auf die Script- und Style-Elemente, die es erzeugt; style-src braucht dann kein 'unsafe-inline'.

<script nonce="SAYFANIZIN-NONCE-DEGERI" src="https://cerez.io/sdk/loader.js" data-cerez-key="API_ANAHTARINIZ"></script>

Beispielrichtlinie (Website ohne Nonce)

Content-Security-Policy:
  script-src 'self' https://cerez.io;
  connect-src 'self' https://cerez.io;
  style-src 'self' 'unsafe-inline' https://cerez.io;
  font-src 'self' https://cerez.io;
  img-src 'self' data: https://cerez.io

Behalten Sie Ihre eigenen Direktiven bei; fügen Sie nur die cerez.io-Domain hinzu.

HÄUFIG GESTELLTE FRAGEN

Technische Fragen

Kısa cevap: SDK cerez.io sunucularından servis edilir ve otomatik güncellenir. Self-hosting sunulmaz; bu sayede yeni özellikler ve güvenlik güncellemeleri otomatik olarak tüm müşterilere ulaşır.

Starten Sie mit einer Zeile Code

Konto erstellen, Domain hinzufügen, Code kopieren. Den Rest übernimmt das SDK.

Kostenlos starten API-Referenz