JavaScript SDK (Client) Entegrasyonu

JS SDK, web projelerinizde sıfır bağımlılık ile en yüksek performansı hedefler. Platformumuz hem sitenizin çerez yönetimi ihtiyaçlarını çözer hem de yasal geçerliliği olan sözleşme/politika onaylarını kolayca elde etmenizi sağlar.

Hızlı Başlangıç

Tek satır script ile başlayın. Banner görünümü, çerez kategorileri, metinler ve bölgesel uyumluluk (GDPR, KVKK, CCPA…) — tümü HashEntry panelinden yönetilir:

<head>
  <script
    src="https://tool.hashentry.com/cmp.js"
    data-site="SİZİN_SİTE_API_ANAHTARINIZ"
    async
  ></script>
</head>

Bu kadar. SDK, API key’inize bağlı config’i sunucudan çeker; banner tasarımı, renkler, dil, kategoriler ve davranış ayarlarının tümü panelden kontrol edilir.

Üçüncü Parti Scriptleri Bloklama

Çerez onayı verilmeden çalışmasını istemediğiniz scriptleri type="text/plain" ile işaretleyin. SDK, kullanıcı onay verdikten sonra bunları otomatik aktive eder:

<!-- Google Analytics — "analytics" kategorisi onaylanana kadar çalışmaz -->
<script type="text/plain" data-cookie-category="analytics">
  (function(i,s,o,g,r,a,m){...})(window,document,'script','https://...');
</script>

<!-- Facebook Pixel — harici script -->
<script type="text/plain" data-cookie-category="marketing"
        data-src="https://connect.facebook.net/en_US/fbevents.js">
</script>

Tercihleri Yeniden Açma

Kullanıcı banner’ı kapattıktan sonra tercihlerini değiştirmek isterse iki yol vardır:

Varsayılan ikon: Banner kapandığında ekranın köşesinde kalıcı bir “Çerez Tercihleri” ikonu görünür. İkonun stili ve konumu panelden ayarlanır.
Kendi butonunuz: İkonu gizleyip footer’a koyduğunuz bir link ile CMP.show() çağırabilirsiniz.

Desteklenen `data-*` Attribute’ları

Attribute	Zorunlu	Varsayılan	Açıklama
`data-site`	✅	—	Site API key’i
`data-mode`	❌	`local-fallback`	Çalışma modu: `remote`, `local`, `local-fallback`
`data-language`	❌	`auto`	Banner dili (`auto` = tarayıcı dili algılanır)
`data-region`	❌	`auto`	Bölge override (`auto` = sunucu GeoIP veya config’deki algılama yöntemi)
`data-config`	❌	—	Inline JSON config (local/local-fallback mod)
`data-debug`	❌	`false`	Geliştirici modu (console logları)
`data-headless`	❌	`false`	UI-less mod (kendi arayüzünüzü kullanmak için)

JavaScript API (`window.CMP`)

SDK yüklendikten sonra window.CMP üzerinden erişilebilen API:

// SDK'nın hazır olduğunu dinle
CMP.ready(() => {
    console.log('HashEntry CMP yüklendi.');
});

// Banner'ı programatik aç/kapat
CMP.show();
CMP.hide();

// Programatik kabul/ret
CMP.accept();                      // Tümünü kabul
CMP.accept({ marketing: false });  // Marketing hariç kabul
CMP.reject();                      // Tümünü reddet

// Mevcut consent durumunu sorgula
const consent = CMP.getConsent();   // { decision, categories, ... }
CMP.hasConsent('analytics');        // true / false

// Consent'e ek bilgi bağla (ör. sipariş no)
CMP.setMetadata({ order_id: 'ORD-54321', customer_id: 'CUST-999' });

// Doküman (sözleşme/politika) onay penceresi aç
CMP.showDocumentApproval('mesafeli-satis-sozlesmesi', {
    transaction_id: 'TRX-101'
}).then(result => {
    if (result.approved) console.log("Onaylandı!", result.proof_hash);
});

// Event dinleme
CMP.on('consent:given', (data) => {
    console.log("Onaylar:", data.categories);
});
CMP.on('banner:shown', () => { ... });
CMP.on('banner:hidden', () => { ... });
CMP.on('language:changed', ({ from, to }) => { ... });

Pre-init Queue

Script yüklenmeden önce API çağrısı yapmak isterseniz queue kullanın:

<script>
window.__CMP_QUEUE = window.__CMP_QUEUE || [];
window.__CMP_QUEUE.push(['setMetadata', { order_id: 'ORD-12345' }]);
window.__CMP_QUEUE.push(['setRegion', 'TR']);
window.__CMP_QUEUE.push(['setLanguage', 'de']);
</script>

Panelden Yönetilenler vs JS API

Yönetim Paneli	JS API (Çalışma Anı)
Banner tasarımı (logo, renkler, köşeler)	`setLanguage` — dil değiştirme
Çerez kategorileri ve açıklamaları	`setRegion` — bölge override
Çok dilli metin şablonları	`setMetadata` — consent’e ek veri bağlama
GeoIP ve bölgesel kurallar	`show` / `hide` — banner kontrolü
Doküman versiyonları	`setConfig` — local config (ileri düzey)
Varsayılan davranış ayarları	`on` / `off` — event dinleme

İleri Düzey: Çalışma Modları

SDK üç farklı modda çalışabilir:

Mod	Davranış	`data-site`	Sunucu
`remote`	Config sunucudan çekilir	Zorunlu	Gerekli
`local`	Tüm config sayfadan sağlanır	Opsiyonel	Yok
`local-fallback` (varsayılan)	Sunucudan çeker, başarısız olursa local config’e düşer	Opsiyonel	Tercihen

Local Mod — Sunucu Bağımsız Kurulum

Sunucuya hiç gitmeden, tüm config’i doğrudan sayfaya gömerek çalıştırabilirsiniz. Özellikle test ortamları, offline senaryolar ve kendi altyapınızı kullanmak istediğiniz durumlar için idealdir.

Not: Local mod yalnızca config kaynağını belirler. Consent kayıtları her modda sunucuya gönderilir — data-site API key’i local modda da consent kaydı için kullanılır.

Yöntem 1 — <script id="cmp-config"> ile (önerilen):

<head>
  <script type="application/json" id="cmp-config">
  {
    "banner_config": {
      "layout": "bottom_bar",
      "mobile_layout": "bottom_bar",
      "region_detection": "timezone",
      "theme": {
        "primary_color": "#2563EB",
        "background_color": "#FFFFFF",
        "text_color": "#1F2937",
        "button_style": "rounded",
        "widget_icon": "cookie",
        "widget_position": "bottom_left",
        "font_family": "system",
        "theme_mode": "auto"
      },
      "content": {
        "title": "Çerez Tercihleriniz",
        "description": "Bu web sitesi, deneyiminizi iyileştirmek için çerezler kullanmaktadır.",
        "accept_button_text": "Tümünü Kabul Et",
        "reject_button_text": "Tümünü Reddet",
        "settings_button_text": "Tercihleri Yönet",
        "save_selected_text": "Seçilenleri Kabul Et",
        "close_text": "Kapat",
        "widget_label": "Çerez Tercihleri"
      },
      "categories": [
        { "key": "necessary", "label": "Zorunlu Çerezler", "description": "Web sitesinin temel işlevleri için gereklidir.", "required": true, "default": true },
        { "key": "analytics", "label": "Analitik", "description": "Ziyaretçi istatistiklerini toplamak için kullanılır.", "required": false, "default": false },
        { "key": "marketing", "label": "Pazarlama", "description": "Reklam ve pazarlama amaçlı çerezler.", "required": false, "default": false },
        { "key": "preferences", "label": "Tercihler", "description": "Kişiselleştirme ve tercih çerezleri.", "required": false, "default": false }
      ],
      "behavior": {
        "show_reject_button": true,
        "show_settings_button": true,
        "show_widget": true,
        "show_powered_by": true,
        "block_page_scroll": false,
        "modal_layout": "sidebar_right",
        "cookie_display_mode": "vendor",
        "banner_animation": "slide_fade",
        "modal_tabs": true,
        "record_informational_consent": false
      }
    }
  }
  </script>

  <script
    src="https://tool.hashentry.com/cmp.js"
    data-mode="local"
    data-language="tr"
    async
  ></script>
</head>

Yöntem 2 — JavaScript API ile (SPA’lar için ideal):

<head>
  <script>
    window.__CMP_QUEUE = window.__CMP_QUEUE || [];
    window.__CMP_QUEUE.push(['setConfig', {
      banner_config: {
        layout: 'bottom_bar',
        region_detection: 'timezone',
        theme: { primary_color: '#2563EB', button_style: 'rounded', font_family: 'system' },
        content: {
          title: 'Çerez Tercihleriniz',
          description: 'Bu web sitesi çerez kullanmaktadır.',
          accept_button_text: 'Tümünü Kabul Et',
          reject_button_text: 'Tümünü Reddet',
          settings_button_text: 'Tercihleri Yönet',
          save_selected_text: 'Seçilenleri Kabul Et',
          close_text: 'Kapat',
          widget_label: 'Çerez Tercihleri',
        },
        behavior: {
          modal_layout: 'sidebar_right',
          modal_tabs: true,
          banner_animation: 'slide_fade'
        },
        categories: [
          { key: 'necessary', label: 'Zorunlu', description: 'Gerekli.', required: true },
          { key: 'analytics', label: 'Analitik', description: 'İstatistik.', required: false },
          { key: 'marketing', label: 'Pazarlama', description: 'Reklamlar.', required: false },
        ],
      }
    }]);
  </script>

  <script src="https://tool.hashentry.com/cmp.js" data-mode="local" async></script>
</head>

Local-Fallback Mod (Varsayılan)

Bu varsayılan moddur. Sunucudan config çekmeyi dener, erişilemezse sayfadaki local config’e düşer. Ne sunucu ne de local config erişilebilir değilse ama kullanıcı daha önce onay verdiyse, kabul edilen kategoriler geçerli kalır ve izinli scriptler aktive edilir.

<head>
  <!-- Fallback config (sunucu erişilemezse kullanılır) -->
  <script type="application/json" id="cmp-config">
  {
    "banner_config": {
      "content": {
        "title": "Cookie Preferences",
        "accept_button_text": "Accept All",
        "reject_button_text": "Reject All",
        "settings_button_text": "Manage"
      },
      "categories": [
        { "key": "necessary", "label": "Necessary", "description": "Required.", "required": true }
      ]
    }
  }
  </script>

  <!-- data-mode belirtilmezse local-fallback varsayılan olarak kullanılır -->
  <script
    src="https://tool.hashentry.com/cmp.js"
    data-site="SİZİN_SİTE_API_ANAHTARINIZ"
    async
  ></script>
</head>

İleri Düzey: Bölge Algılama (`region_detection`)

Remote modda bölge bilgisi sunucunun GeoIP’sinden gelir. Local veya local-fallback modda data-region verilmezse, config’deki region_detection ayarıyla bölge otomatik algılanabilir:

Yöntem	Nasıl Çalışır	Ağ İsteği
`timezone`	Tarayıcı timezone’undan ülke tahmini (120+ eşleme)	Yok
`freegeoip`	Ücretsiz IP → ülke servisi (3s timeout, başarısız olursa timezone fallback)	Evet

Çözümleme sırası:

1. CMP.setRegion('TR')        → explicit override (en yüksek öncelik)
2. data-region="TR"            → explicit override
3. config.region_detection     → 'freegeoip' veya 'timezone'
4. Fallback → EU               → en kısıtlayıcı bölge (GDPR uygulanır)

<!-- Timezone ile otomatik bölge algılama -->
<script type="application/json" id="cmp-config">
{
  "banner_config": {
    "region_detection": "timezone",
    "content": { ... }
  }
}
</script>
<script src="cmp.js" data-mode="local" async></script>

İleri Düzey: Çoklu Dil Desteği

Remote modda çeviriler panelden yönetilir. Local modda iki yöntemle çoklu dil sağlayabilirsiniz:

Yöntem 1: Config içinde `languages.translations`

<script type="application/json" id="cmp-config">
{
  "banner_config": {
    "languages": {
      "default": "tr",
      "translations": {
        "tr": {
          "banner": { "title": "Çerez Tercihleriniz", "acceptAll": "Tümünü Kabul Et", "rejectAll": "Tümünü Reddet", "managePreferences": "Tercihleri Yönet", "save": "Kaydet", "saveSelected": "Seçilenleri Kabul Et", "close": "Kapat" },
          "categories": { "necessary": "Zorunlu", "necessaryDesc": "Gerekli.", "analytics": "Analitik", "analyticsDesc": "İstatistik." },
          "modal": { "title": "Çerez Yönetimi", "description": "Kategorileri seçin.", "alwaysActive": "Her Zaman Aktif" },
          "widget": { "label": "Çerez Tercihleri" }
        },
        "en": {
          "banner": { "title": "Cookie Preferences", "acceptAll": "Accept All", "rejectAll": "Reject All", "managePreferences": "Manage", "save": "Save", "saveSelected": "Accept Selected", "close": "Close" },
          "categories": { "necessary": "Necessary", "necessaryDesc": "Required.", "analytics": "Analytics", "analyticsDesc": "Statistics." },
          "modal": { "title": "Manage Cookies", "description": "Choose categories.", "alwaysActive": "Always Active" },
          "widget": { "label": "Cookie Settings" }
        }
      }
    },
    "content": { ... },
    "categories": [ ... ]
  }
}
</script>

Yöntem 2: JS API ile `CMP.setLocale`

// Almanca dil verisi göm
CMP.setLocale('de', {
  banner: { title: 'Cookie-Einstellungen', acceptAll: 'Alle akzeptieren', rejectAll: 'Alle ablehnen', managePreferences: 'Einstellungen', save: 'Speichern', saveSelected: 'Ausgewählte akzeptieren', close: 'Schließen' },
  categories: { necessary: 'Notwendig', necessaryDesc: 'Erforderlich.', analytics: 'Analytik', analyticsDesc: 'Statistiken.' },
  modal: { title: 'Cookie-Einstellungen verwalten', description: 'Kategorien wählen.', alwaysActive: 'Immer aktiv' },
  widget: { label: 'Cookies' }
});

// Dili Almanca'ya geçir
CMP.setLanguage('de');