@pdntechnology/cookie-consent

v1.2.0

Published

24 days ago

Lightweight Google Consent Mode v2 CMP for React and Next.js

0High
0Medium
0Low

pdntechnologyturkey

cookie-consent consent-mode google-consent-mode consent-mode-v2 gtm google-tag-manager gdpr cmp react nextjs

@pdntechnology/cookie-consent

React ve Next.js için hafif, açık kaynak bir Çerez Yönetim Platformu (CMP). Google Consent Mode v2 akışını sertifikalı araçlarla aynı şekilde uygular.

Ağır bağımlılık yok. Vendor lock-in yok. Google Tag Manager, GA4, Google Ads ve Meta Pixel ile uyumludur.

English documentation: README.md

Neden var?

Google sertifikalı CMP'ler (Cookiebot, OneTrust, CookieYes, …) aynı teknik akışı izler:

Google etiketlerinden önce varsayılanları reddedilmiş olarak ayarla
GTM / gtag.js yükle
Çerez banner'ını göster
Kullanıcı seçimi → gtag('consent', 'update', …) + dataLayer olayı
Reklamlar reddedildiğinde → ads_data_redaction ve url_passthrough etkinleştir

Bu kütüphane bu akışı okunabilir, yaklaşık 15 KB JavaScript ile uygular.

Not: Sertifikalı CMP'ler ayrıca IAB TCF v2.2 sinyalleri sağlar ve Google'ın sertifikalı satıcı listesinde yer alır. Bu kütüphane Consent Mode v2 teknik entegrasyonunu kapsar. Gizlilik politikası metni ve yasal uyumluluk sizin sorumluluğunuzdadır.

Özellikler

Google Consent Mode v2 (7 sinyalin tamamı)
Granüler kategoriler: Zorunlu / Analitik / Pazarlama
Özelleştirilebilir banner metni, tema renkleri ve çerez envanteri
Bootstrap ve güncellemede ads_data_redaction + url_passthrough
Bölgesel varsayılan onay (EEA vb.)
React banner + Next.js bootstrap bileşeni
İsteğe bağlı GTM ve Meta Pixel yükleyicileri (onay kapılı)
Framework'ten bağımsız çekirdek API (vanilla JS desteklenir)
Çekirdek API ve React bileşenleri için TypeScript tanımları
Onay kaydedilemediğinde hata callback'leri

Kurulum

npm install @pdntechnology/cookie-consent

Next.js ayarı

next.config.mjs dosyasına ekleyin:

const nextConfig = {
  transpilePackages: ["@pdntechnology/cookie-consent"],
};

Hızlı başlangıç

1. Yapılandırma (isteğe bağlı)

// lib/consent-config.js
import { configureConsent } from "@pdntechnology/cookie-consent";

configureConsent({
  storageKey: "site_cerez_tercihi",
  waitForUpdateMs: 500,
  adsDataRedaction: true,
  urlPassthrough: true,
  debug: false,
});

Bu dosyayı root layout'ta ConsentBootstrap'ten önce import edin.

2. Consent varsayılanlarını bootstrap et (GTM'den önce)

// app/layout.jsx
import "@pdntechnology/cookie-consent/styles.css";
import "@/lib/consent-config";
import { ConsentBootstrap } from "@pdntechnology/cookie-consent/react";

export default function RootLayout({ children }) {
  return (
    <html lang="tr">
      <body>
        <ConsentBootstrap />
        {children}
      </body>
    </html>
  );
}

3. Banner + etiketler

// app/providers.jsx
import Link from "next/link";
import {
  CookieConsent,
  GoogleTagManager,
} from "@pdntechnology/cookie-consent/react";

export function Providers({ children }) {
  return (
    <>
      {children}
      <CookieConsent
        policyHref="/cerez-politikasi"
        LinkComponent={Link}
        labels={{
          title: "Çerez tercihleri",
          message: "Deneyiminizi iyileştirmek için çerez kullanıyoruz.",
          policyLink: "Çerez politikası",
          accept: "Tümünü kabul et",
          reject: "Tümünü reddet",
          manage: "Tercihleri yönet",
        }}
        theme={{
          primary: "#2563eb",
          background: "rgba(15, 23, 42, 0.97)",
        }}
      />
      <GoogleTagManager gtmId="GTM-XXXXXXX" />
    </>
  );
}

4. Tercihleri yeniden aç (footer linki)

import { openPreferences } from "@pdntechnology/cookie-consent";

<button type="button" onClick={openPreferences}>
  Çerez ayarları
</button>

Özelleştirme

Metin ve politika URL'si

Görünen tüm metinler labels prop'u ile değiştirilebilir. Politika linki policyHref ile ayarlanır.

| Label anahtarı | Varsayılan (EN) | |----------------|-----------------| | title | Cookie preferences | | message | We use cookies to improve your experience… | | policyLink | Privacy policy | | accept | Accept all | | reject | Reject all | | manage | Manage preferences | | save | Save preferences | | necessaryTitle | Necessary | | necessaryDescription | Required for core site functionality… | | analyticsTitle | Analytics | | analyticsDescription | Helps us understand how visitors use the site… | | marketingTitle | Marketing | | marketingDescription | Used for ads and remarketing… | | alwaysOn | Always on | | cookiesHeading | View cookies | | cookieName | Name | | cookiePurpose | Purpose | | cookieDuration | Duration | | cookieProvider | Provider | | storageError | Your preferences could not be saved… |

Tema renkleri

theme prop'u ile CSS değişkenlerini override edin:

<CookieConsent
  theme={{
    background: "rgba(15, 23, 42, 0.97)",
    text: "#f8fafc",
    link: "#93c5fd",
    primary: "#2563eb",
    accent: "#2563eb",
  }}
/>

Desteklenen anahtarlar: background, text, textMuted, link, primary, primaryText, secondaryBackground, border, accent.

Çerez envanteri tablosu

Hangi çerezlerin kullanıldığını tercihler panelinde göstermek için cookies dizisi verin:

<CookieConsent
  cookies={[
    {
      category: "necessary",
      name: "site_cerez_tercihi",
      purpose: "Çerez tercihlerinizi saklar",
      duration: "1 yıl",
      provider: "Bu site",
    },
    {
      category: "analytics",
      name: "_ga",
      purpose: "Ziyaretçi istatistikleri",
      duration: "2 yıl",
      provider: "Google Analytics",
    },
    {
      category: "marketing",
      name: "_fbp",
      purpose: "Reklam hedefleme",
      duration: "3 ay",
      provider: "Meta",
    },
  ]}
  labels={{
    cookiesHeading: "Kullanılan çerezleri gör",
    cookieName: "Ad",
    cookiePurpose: "Amaç",
    cookieDuration: "Süre",
    cookieProvider: "Sağlayıcı",
  }}
/>

cookies verilmezse banner mevcut üç kategori görünümünü korur.

Hata yönetimi

const result = acceptAll();
if (!result.ok) {
  console.error(result.reason); // "invalid" | "storage"
}

React'te callback kullanın:

<CookieConsent
  onConsentSaved={(consent) => console.log("kaydedildi", consent)}
  onConsentError={({ reason }) => console.warn("hata", reason)}
/>

configureConsent({ debug: true }) ile konsola uyarı yazılır. Global işlem için onStorageError kullanılabilir.

Örnek uygulama

examples/next-app dizininde Türkçe metinler, özel tema ve çerez envanteri içeren çalışan bir Next.js demosu vardır.

cd examples/next-app
npm install
npm run dev

Kategoriler → Google sinyalleri

| Banner kategorisi | Kullanıcı seçimi | Google Consent Mode sinyalleri | |-------------------|------------------|--------------------------------| | Zorunlu | Her zaman açık | security_storage: granted | | Analitik | Opt-in | analytics_storage | | Pazarlama | Opt-in | ad_storage, ad_user_data, ad_personalization, functionality_storage, personalization_storage |

Pazarlama reddedildiğinde kütüphane ayrıca şunları ayarlar:

ads_data_redaction: true
url_passthrough: true

API referansı

Yapılandırma

| Fonksiyon | Açıklama | |-----------|----------| | configureConsent(config) | Depolama anahtarı, bekleme süresi, bölgesel varsayılanlar | | getConsentConfig() | Aktif yapılandırmayı oku |

Kullanıcı onayı

| Fonksiyon | Açıklama | |-----------|----------| | getConsent() | Kayıtlı tercihleri oku | | setConsent({ analytics, marketing }) | Özel seçim kaydet; { ok, consent \| reason } döner | | acceptAll() | Tüm kategorilere izin ver | | rejectAll() | Opsiyonel kategorileri reddet | | hasAnalyticsConsent() | Analitik onayını kontrol et | | hasMarketingConsent() | Pazarlama onayını kontrol et | | openPreferences() | Tercih panelini yeniden aç | | syncConsentFromStorage() | GTM yüklendikten sonra kayıtlı onayı uygula |

`CookieConsent` prop'ları

| Prop | Tip | Açıklama | |------|-----|----------| | labels | object | Banner metinlerini override et | | theme | object | Banner renklerini override et | | cookies | CookieEntry[] | Opsiyonel çerez envanteri tablosu | | policyHref | string | Gizlilik / çerez politikası URL'si | | LinkComponent | component | Özel link bileşeni (varsayılan: Next.js Link) | | className | string | Banner kök elemanına ek CSS sınıfı | | onConsentSaved | (consent) => void | Başarılı kayıttan sonra çağrılır | | onConsentError | ({ reason }) => void | Kayıt başarısız olursa çağrılır |

Sorun giderme

| Sorun | Olası neden | Çözüm | |-------|-------------|-------| | Banner hiç görünmüyor | Onay zaten kayıtlı | localStorage anahtarını temizleyin veya openPreferences() çağırın | | GTM onaydan önce tetikleniyor | Bootstrap eksik veya geç yükleniyor | GTM'den önce <ConsentBootstrap /> ekleyin | | Onay kaydedilmiyor | Depolama engelli (gizli mod, Safari ITP) | onConsentError ile yakalayın; banner inline hata gösterir | | Reddetmeden sonra etiketler çalışıyor | GTM etiketleri Consent Mode kullanmıyor | GTM'de Consent Mode'u etkinleştirin | | ./react TypeScript hatası | Eski sürüm | v1.1+ ile @pdntechnology/cookie-consent/react tipleri dahildir |

Katkıda bulunma

Bkz. CONTRIBUTING.md.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@pdntechnology/cookie-consent

Neden var?

Özellikler

Kurulum

Next.js ayarı

Hızlı başlangıç

1. Yapılandırma (isteğe bağlı)

2. Consent varsayılanlarını bootstrap et (GTM'den önce)

3. Banner + etiketler

4. Tercihleri yeniden aç (footer linki)

Özelleştirme

Metin ve politika URL'si

Tema renkleri

Çerez envanteri tablosu

Hata yönetimi

Örnek uygulama

Kategoriler → Google sinyalleri

API referansı

Yapılandırma

Kullanıcı onayı

CookieConsent prop'ları

Sorun giderme

Katkıda bulunma

Lisans

`CookieConsent` prop'ları