Dokumentation, Installation, Konfiguration, Integrationen

Q: Wird das SDK über ein CDN geladen oder sollte ich es auf meinem eigenen Server hosten?

Kurze Antwort: Das SDK wird schnell über CDN ausgeliefert und automatisch aktualisiert. Self-Hosting wird nicht angeboten.

Q: Arbeitet das SDK mit Shadow DOM?

Kurze Antwort: Ja. Sowohl das Cookie SDK als auch das Accessibility SDK nutzen eine Shadow-DOM-Architektur, sodass es keine Konflikte mit dem CSS Ihrer Website gibt; es lädt asynchron und blockiert den First Paint nicht.

Q: Gibt es ein npm-Paket?

Kurze Antwort: Das Paket @cerezsuite/consent v0.1.0-beta ist fertig, npm-Publish in Q3 2026. Verwenden Sie für React/Next.js vorerst die Script-Tag-Anleitung.

Q: Wie wird die Cache-Dauer eingestellt?

Kurze Antwort: Die Banner-Konfiguration wird 5 Minuten auf dem Server zwischengespeichert. Auf der Browserseite wird sessionStorage verwendet. Zum Leeren des Caches gehen Sie zu Admin-Panel > Site-Einstellungen > Cache leeren.

Q: Kann ich ein einziges Embed für mehrere Domains verwenden?

Kurze Antwort: Nein. Für jede Domain wird ein separater API Key ausgestellt. Sie können mehrere Domains unter einem Plan verwalten, aber jede Domain muss ihren eigenen Embed-Code verwenden.

Q: Schreibt das SDK irgendwelche Cookies?

Kurze Antwort: Es schreibt nur ein einziges funktionales Cookie: cb_consent (das die Einwilligungsentscheidung speichert). Da dieses Cookie zur Kategorie functional gehört, erfordert es keine Einwilligung des Nutzers.

Q: Ist es mit Server-Side Rendering (SSR) kompatibel?

Kurze Antwort: Ja. Das SDK läuft ausschließlich im Browser und beeinflusst das Rendering während Next.js/Nuxt SSR nicht. Wir empfehlen die Verwendung von Script strategy='afterInteractive'.

Q: Ist für CSP (Content Security Policy) eine Konfiguration erforderlich?

Kurze Antwort: Es genügt, https://cerez.io zu Ihrer script-src-Direktive hinzuzufügen. Das SDK verwendet keine Inline-Skripte; es funktioniert mit einer nonce-freien CSP.

SCHNELLSTART

Ein funktionierendes Banner in 3 Schritten

Folgen Sie den untenstehenden Schritten. Innerhalb von 5 Minuten haben Sie ein Live-Banner auf Ihrer Website.

Konto erstellen

14 Tage kostenlose Pro-Testphase. Keine Kreditkarte erforderlich; mit Ihrer E-Mail-Adresse sind Sie in Sekunden startklar.

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 Embed-Code 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 vor dem Schließen des <head>-Tags Ihrer Website ein. Den Wert für data-cerez-key erhalten Sie im Admin-Panel > Installation.

<!-- cerez.io Cookie Consent + Accessibility -->
<script src="https://cerez.io/sdk/consent.js"
        data-cerez-key="YOUR_API_KEY"
        async></script>

Wichtig Das async-Attribut ist verpflichtend; andernfalls kann das SDK den First Paint der Seite verzögern. Die Konfiguration wird 5 Minuten serverseitig zwischengespeichert; das SDK übernimmt Ihre Änderungen beim nächsten Laden.

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 das Skript in das <head>-Tag ein. Die Einrichtung dauert 30 Sekunden.

<head>
  <!-- mevcut etiketler -->
  <script src="https://cerez.io/sdk/consent.js"
          data-cerez-key="YOUR_KEY" async></script>
</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/consent.js"
  data-cerez-key="YOUR_KEY" async></script>';
});

Shopify

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

<!-- theme.liquid içinde, </head> öncesine -->
<script
  src="https://cerez.io/sdk/consent.js"
  data-cerez-key="YOUR_KEY"
  async></script>

Next.js / React

Verwenden Sie <Script strategy="afterInteractive"> in _app.tsx.

// pages/_app.tsx
import Script from 'next/script'

export default function App({ Component, pageProps }) {
  return (
    <>
      <Script
        src="https://cerez.io/sdk/consent.js"
        data-cerez-key="YOUR_KEY"
        strategy="afterInteractive"
      />
      <Component {...pageProps} />
    </>
  )
}

Google Tag Manager

Erstellen Sie ein Custom-HTML-Tag und veröffentlichen Sie es mit einem All-Pages-Trigger.

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

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

Webflow

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

<!-- Site Settings > Custom Code > Head Code -->
<script
  src="https://cerez.io/sdk/consent.js"
  data-cerez-key="YOUR_KEY"
  async></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). Die automatische Blockierung erfolgt über die Attribute 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"
  data-cb-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

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'
});

Eine ausführliche GCM-v2-Anleitung finden Sie auf der Google Consent Mode v2-Seite.

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

Es genügt, https://cerez.io zu Ihrer script-src-Direktive hinzuzufügen. Das SDK verwendet keine Inline-Skripte; es benötigt keine Nonce.

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).

HÄUFIG GESTELLTE FRAGEN

Technische Fragen

Wird das SDK über ein CDN geladen oder sollte ich es auf meinem eigenen Server hosten?

Kurze Antwort: Das SDK wird schnell über CDN ausgeliefert und automatisch aktualisiert. Self-Hosting wird nicht angeboten; so erreichen neue Funktionen und Sicherheitsupdates automatisch alle Kunden.

Arbeitet das SDK mit Shadow DOM?

Gibt es ein npm-Paket?

Kurze Antwort: Das Paket @cerezsuite/consent v0.1.0-beta ist fertig. Das Ziel für die Veröffentlichung in der npm-Registry ist Q3 2026. Vorerst wird die Anleitung <Script strategy="afterInteractive"> empfohlen (siehe den Next.js-Abschnitt auf dieser Seite).

Wie wird die Cache-Dauer eingestellt?

Kann ich ein einziges Embed für mehrere Domains verwenden?

Schreibt das SDK irgendwelche Cookies?

Kurze Antwort: Es schreibt nur ein einziges funktionales Cookie: cb_consent (das die Einwilligungsentscheidung speichert, Standard 180 Tage). Da dieses Cookie zur Kategorie functional gehört, erfordert es im Rahmen von KVKK/GDPR keine Einwilligung des Nutzers.

Ist es mit Server-Side Rendering (SSR) kompatibel?

Kurze Antwort: Ja. Das SDK läuft ausschließlich im Browser; es beeinflusst das Rendering während des Next.js/Nuxt-SSR-Prozesses nicht. Wir empfehlen die Verwendung von <Script strategy="afterInteractive">. Es kommt zu keinem Hydration Mismatch.

Ist für CSP (Content Security Policy) eine spezielle Konfiguration erforderlich?

Kurze Antwort: Es genügt, https://cerez.io zu Ihrer script-src-Direktive hinzuzufügen. Das SDK verwendet keine Inline-Skripte; es funktioniert mit einer nonce-freien CSP.

Installation in 5 Minuten, unbegrenzte Anpassung