pdn/cookie-consent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
cookie-consent/README.tr.md
Pdn Technology 9a001197e1
Some checks are pending
CI / test (20) (push) Waiting to run
Details
CI / test (22) (push) Waiting to run
Details
Tema ayarları eklendi
2026-06-20 08:58:11 +03:00

9.8 KiB
Raw Permalink Blame History

@pdntechnology/cookie-consent

License: MIT npm version

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:

  1. Google etiketlerinden önce varsayılanları reddedilmiş olarak ayarla
  2. GTM / gtag.js yükle
  3. Çerez banner'ını göster
  4. Kullanıcı seçimi → gtag('consent', 'update', …) + dataLayer olayı
  5. 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.

Lisans

MIT © PDN Technology