# @pdntechnology/cookie-consent
[](LICENSE)
[](https://www.npmjs.com/package/@pdntechnology/cookie-consent)
React ve Next.js için hafif, açık kaynak bir **Çerez Yönetim Platformu (CMP)**. [Google Consent Mode v2](https://developers.google.com/tag-platform/security/guides/consent) 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](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
```bash
npm install @pdntechnology/cookie-consent
```
### Next.js ayarı
`next.config.mjs` dosyasına ekleyin:
```js
const nextConfig = {
transpilePackages: ["@pdntechnology/cookie-consent"],
};
```
---
## Hızlı başlangıç
### 1. Yapılandırma (isteğe bağlı)
```js
// 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)
```jsx
// 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 (
{children}
);
}
```
### 3. Banner + etiketler
```jsx
// app/providers.jsx
import Link from "next/link";
import {
CookieConsent,
GoogleTagManager,
} from "@pdntechnology/cookie-consent/react";
export function Providers({ children }) {
return (
<>
{children}
);
}
```
### 4. Tercihleri yeniden aç (footer linki)
```jsx
import { openPreferences } from "@pdntechnology/cookie-consent";
```
---
## Ö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:
```jsx
```
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:
```jsx
```
`cookies` verilmezse banner mevcut üç kategori görünümünü korur.
### Hata yönetimi
```js
const result = acceptAll();
if (!result.ok) {
console.error(result.reason); // "invalid" | "storage"
}
```
React'te callback kullanın:
```jsx
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`](examples/next-app) dizininde Türkçe metinler, özel tema ve çerez envanteri içeren çalışan bir Next.js demosu vardır.
```bash
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 `` 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](CONTRIBUTING.md).
---
## Lisans
[MIT](LICENSE) © [PDN Technology](https://pdntechnology.com)