# Blakfy Cookie Widget > [![CI](https://github.com/tariktunc/blakfy-cookie/actions/workflows/test.yml/badge.svg)](https://github.com/tariktunc/blakfy-cookie/actions/workflows/test.yml) [![npm version](https://img.shields.io/npm/v/@blakfy/cookie.svg)](https://www.npmjs.com/package/@blakfy/cookie) [![npm downloads](https://img.shields.io/npm/dm/@blakfy/cookie.svg)](https://www.npmjs.com/package/@blakfy/cookie) ![MIT](https://img.shields.io/badge/license-MIT-blue) ![size](https://img.shields.io/badge/size-30.2KB-success) ![tests](https://img.shields.io/badge/tests-365-success) ![langs](https://img.shields.io/badge/languages-23-orange) ![presets](https://img.shields.io/badge/presets-18-purple) > > Tek script ile **KVKK + GDPR + CCPA + Google CMv2 + Microsoft UET + Yandex Metrica + IAB TCF v2.2** uyumlu cookie consent (çerez onayı) widget. **23 dil**, **18 hazır preset** (üçüncü parti araç entegrasyonu), **3 renk teması**, **3-tab tercihler modalı** (Kategoriler / Hizmetler / Hakkında), **tag-gating** (script engelleme/serbest bırakma) dahil. **Versiyon:** 2.2.0 • **Lisans:** MIT • **npm:** `@blakfy/cookie@2.2.0` · `@blakfy/cookie-next@2.2.0` • **CDN:** `cdn.jsdelivr.net/npm/@blakfy/cookie@2.2.0` --- ## Installation İki yol var. Birini seç. ### A) CDN (önerilen — sıfır konfigürasyon) | Strateji | URL | Ne zaman kullan | | --------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------- | | **Pinned** (sabit sürüm) | `cdn.jsdelivr.net/npm/@blakfy/cookie@2.2.0/dist/cookie.min.js` | Production — değişikliklerin gözden geçirilerek kabul edilmesini istersen | | **Auto-patch** (semver tag) | `cdn.jsdelivr.net/npm/@blakfy/cookie@2/dist/cookie.min.js` | Otomatik güvenlik/patch güncellemeleri — major (`@3`) gelene kadar takip eder | unpkg da çalışır: `unpkg.com/@blakfy/cookie@2.2.0/dist/cookie.min.js`. ### B) npm / bundler (Vite, Webpack, Rollup, Astro) ```bash npm i @blakfy/cookie # Vanilla / bundler için widget npm i @blakfy/cookie-next # Next.js / React wrapper (cookie'yi peer olarak çekmez, sadece wrapper) ``` ```js // app.js veya main.js import "@blakfy/cookie"; ``` Bundler ile gelen versiyonu kontrol etmek için: `import { version } from "@blakfy/cookie"` mevcut değil — runtime'da `window.BlakfyCookie.version`. > 💡 **Public API:** `window.BlakfyCookie` global'i hem CDN hem npm install yöntemiyle aynı şekilde tanımlanır. Aşağıdaki Quick Start CDN örneğindedir; npm install ediyorsan ` ``` ### 2. Site içerik script'lerin (GTM/GA4/Pixel/Clarity vb.) Bunlar olduğu gibi kalır. Bootstrap zaten consent default'larını `denied` olarak set etti, dolayısıyla bu tag'ler kullanıcı onay verene kadar cookie yazmaz. ```html ``` ### 3. Widget (body sonu, ``'den önce) ```html ``` **Bittiğinde:** Sayfa yüklendiğinde **alt-orta**'da (varsayılan) consent banner ve "Powered by Blakfy Studio" badge belirir. Konumu değiştirmek için `data-blakfy-position` ile `bottom-right`, `bottom-left`, `top-center`, `top-right`, `top-left` seçeneklerinden birini ver. Kullanıcı bir karar verene kadar GTM/GA4/Facebook Pixel/Clarity tag'leri çalışmaz; karar verildiğinde otomatik aktif olur. --- ## Senaryolar ### Vanilla HTML / WordPress / Shopify Yukarıdaki 3 adımı `` ve `` öncesine yapıştır. Çalışır. Tam çalışan örnek için: [`examples/vanilla-html.html`](./examples/vanilla-html.html). WordPress için PHP snippet: [`examples/wordpress-snippet.php`](./examples/wordpress-snippet.php). Shopify için: theme `theme.liquid` dosyasının `` ve `` öncesi noktalarına aynı 3 adım eklenir. Ek bir paket gerekmez. ### Next.js 14+ (önerilen — App Router) ```bash npm install @blakfy/cookie-next@2 ``` `app/layout.tsx`: ```tsx import { BlakfyCookieProvider, ConsentModeDefault } from "@blakfy/cookie-next"; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {/* Bootstrap: GCM/UET/Yandex default denied */} {children} ); } ``` **`@blakfy/cookie-next` export'ları:** | Export | Tip | Açıklama | | ---------------------- | --------------- | ---------------------------------------------------------------------------------------------------- | | `BlakfyCookieProvider` | React component | Widget'ı `next/script beforeInteractive` ile yükler. Tüm `data-blakfy-*` attribute'ları prop olarak. | | `ConsentModeDefault` | React component | Bootstrap script'i (gtag/uetq/ym defaults `denied`). `` içinde kullan. | | `useBlakfyConsent()` | Hook | Mevcut consent state'i döndürür, değişimde re-render. | | `useGating(category)` | Hook | Belirtilen kategori onaylı mı (`boolean`). Conditional render için. | | `useTcf()` | Hook | TCF v2.2 TC string ve event listener wrapper'ı. | Tam Next.js (App Router) örneği: [`examples/nextjs/`](./examples/nextjs/). Paket README'si: [`packages/cookie-next/README.md`](./packages/cookie-next/README.md). ### Next.js Pages Router (legacy projeler) Aynı paket Pages Router ile de çalışır — provider router-agnostik. `pages/_app.tsx`: ```tsx import type { AppProps } from "next/app"; import { BlakfyCookieProvider, ConsentModeDefault } from "@blakfy/cookie-next"; export default function App({ Component, pageProps }: AppProps) { return ( <> ); } ``` `ConsentModeDefault`'u `_document.tsx`'in `` içine de koyabilirsin (daha erken yükleme). Provider `next/script beforeInteractive` ile yüklendiği için ekstra konfig gerekmez. ### GTM ile birlikte GTM, default `denied` ile başlar (bootstrap sayesinde). Trigger'larında "Consent State" şartı eklemen yeterli — Tag → "Consent settings" → "Require additional consent for tag firing" → ilgili kategoriler (örn. `analytics_storage` veya `ad_storage`). Kullanıcı kabul edince `gtag('consent','update', ...)` otomatik çağrılır ve tag'ler kendiliğinden tetiklenir. ```js // Doğrulama (DevTools console) window.dataLayer.find((e) => e[0] === "consent"); // → ["consent", "default", { ad_storage: "denied", ... }] window.BlakfyCookie.acceptAll(); // → ["consent", "update", { ad_storage: "granted", ... }] ``` ### Bing Ads (Microsoft UET) ile UET tag'ini olduğu gibi koy — bootstrap `window.uetq.push('consent','default',{ad_storage:'denied'})` çağrısını otomatik yapar. Kullanıcı `marketing` onayı verince UET'e `update` push edilir. Microsoft Clarity de aynı sinyali okur. ```html ``` ### Yandex Metrica ile Yandex'in standart consent API'si yoktur, tag-gating kullanılır. Metrica embed kodunu `type="text/plain"` ile sar: ```html ``` **Webvisor (session replay)** için ayrı `recording` kategori onayı gerekir (KVKK/GDPR yorumu). Otomatik temizlenen cookie'ler: `_ym_*`, `yandexuid`, `yabs-frequency`. --- ## Tercihler Modalı (3 Sekme) "Tercihler" veya `window.BlakfyCookie.open()` çağrıldığında açılan modal 3 sekmeden oluşur: | Sekme | İçerik | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Kategoriler** | Zorunlu / Analitik / Pazarlama / Fonksiyonel toggle switch'leri. "Seçimleri Kaydet" ve "Tümünü Kabul Et" butonları. | | **Hizmetler** | Aktif preset'lere göre accordion kartlar. Her kart: açıklama, veri işleyici, adres, amaçlar, teknolojiler, toplanan veriler, hukuki dayanak, saklama süresi, aktarım ülkeleri, gizlilik politikası linki. GDPR Madde 13/14 + KVKK Madde 10 zorunlu bilgi ifşası. | | **Hakkında** | CMP kimliği (Blakfy Studio), platform açıklaması (GDPR / KVKK / CCPA), sürüm numarası. | > **Yasal dayanak:** Hizmetler sekmesindeki bilgiler GDPR Madde 13/14 (bilgi yükümlülüğü) ve KVKK Madde 10 (aydınlatma yükümlülüğü) gerekliliklerini karşılar. Presets kullanmadan da her site kendi hizmet bilgilerini `SERVICE_METADATA` yapısına ekleyebilir. --- ## Renk Temaları 3 hazır tema, `data-blakfy-theme` ile seçilir: | Tema | Açıklama | Attribute değeri | | ---------------------- | ------------------------------------------ | ------------------------ | | **Beyaz** (varsayılan) | Beyaz arka plan, koyu metin | `light` veya atlanabilir | | **Açık gri** | `#f0f0f0` arka plan, koyu metin | `gray` | | **Siyah** | `#1a1a1a` arka plan, açık metin | `dark` | | **Otomatik** | Sistem `prefers-color-scheme` ayarını okur | `auto` | ```html ``` Tüm temalarda `--blakfy-accent` CSS değişkeni geçerliliğini korur — buton ve aktif sekme rengi `data-blakfy-accent` ile özelleştirilebilir. --- ## Configuration Reference Tüm ` ``` Onay verildiğinde widget script'in `type` attribute'unu `text/javascript`'e çevirir, `data-blakfy-src` → `src` taşır ve DOM'a yeniden ekler. ### Inline script ```html ``` ### Iframe (YouTube, Vimeo, harita, vb.) ```html ``` `data-blakfy-placeholder="auto"` → otomatik "Çerez onayı bekleniyor" placeholder UI'ı gösterilir. ### React/Next.js declarative gating ```tsx "use client"; import { useGating } from "@blakfy/cookie-next"; export function YouTubeEmbed({ id }: { id: string }) { const allowed = useGating("marketing"); if (!allowed) { return (

Onay bekleniyor — bu içeriği görmek için pazarlama çerezlerini kabul edin.

); } return (