345 lines
9.8 KiB
Markdown
345 lines
9.8 KiB
Markdown
# @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 (
|
||
<html lang="tr">
|
||
<body>
|
||
<ConsentBootstrap />
|
||
{children}
|
||
</body>
|
||
</html>
|
||
);
|
||
}
|
||
```
|
||
|
||
### 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}
|
||
<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)
|
||
|
||
```jsx
|
||
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:
|
||
|
||
```jsx
|
||
<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:
|
||
|
||
```jsx
|
||
<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
|
||
|
||
```js
|
||
const result = acceptAll();
|
||
if (!result.ok) {
|
||
console.error(result.reason); // "invalid" | "storage"
|
||
}
|
||
```
|
||
|
||
React'te callback kullanın:
|
||
|
||
```jsx
|
||
<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`](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 `<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](CONTRIBUTING.md).
|
||
|
||
---
|
||
|
||
## Lisans
|
||
|
||
[MIT](LICENSE) © [PDN Technology](https://pdntechnology.com)
|