JavaScript SDK (Client) Entegrasyonu

HashEntry CMP SDK, çerez banner’ını gösteren, etiketlediğiniz scriptleri ziyaretçi izin verene kadar engelleyen ve her kararı HashEntry sunucusuna kaydeden, bağımlılığı olmayan bir scripttir. Doküman onaylarını da (kullanım koşulları, sözleşmeler, politikalar) kaydedebilir — bkz. Doküman Onayı ve İmza.

Bu sayfa SDK’nın bugün ne yaptığını anlatır. Bir davranış panel ayarına veya sizin kendi işaretlemenize (markup) bağlıysa, bu ayrıca belirtilir.

---

Hızlı Başlangıç

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

SDK, API anahtarınıza bağlı yapılandırmayı (banner tasarımı, metinler, kategoriler, dokümanlar, davranış ayarları) sunucudan yükler ve bu ziyaretçi için banner gerekip gerekmediğine karar verir.

Bir çerez kararının sunucuya kaydedilebilmesi için iki koşulun sağlanmış olması gerekir:

1. Site panelde doğrulanmış olmalıdır. Doğrulanmamış bir siteye ait istekler 403 SITE_NOT_VERIFIED ile reddedilir.
2. Siteye bir çerez politikası dokümanı bağlanmış olmalıdır. Bir sonraki bölüme bakın.

Çerez politikası dokümanı zorunludur

Bir çerez onayı, yalnızca siteye bağlı cookie_policy türündeki bir dokümanın tam olarak aktif olan sürümüne referans veriyorsa kaydedilir. Kabul edilen politika sürümü delilin bir parçasıdır; bu nedenle SDK bu kuralı esnetmez.

• Siteye bağlı, yayımlanmış bir çerez politikası yoksa SDK banner’ı göstermez (widget’ı ve “Do Not Sell” bağlantısını da) ve her bölgede, işaretlenmiş zorunlu olmayan tüm scriptleri bloklu tutar: kanıt olarak kaydedilemeyecek bir tercih toplanmaz. consent:error ve error olayları code: "COOKIE_POLICY_MISSING" ile tetiklenir ve hata tarayıcı konsoluna yazılır. CMP.accept() / CMP.reject() sonucu success: false, error.code = "COOKIE_POLICY_MISSING" ve pending_sync: false olur; hiçbir şey saklanmaz, uygulanmaz veya kuyruğa alınmaz. Bir politika bağlandığında banner bir sonraki sayfa yüklemesinde görünür ve ziyaretçi o sürüme göre karar verir. Politika bağlıyken kaydedilmiş bir onay geçerliliğini korur.
• Bir karar hiçbir zaman bekletilip, ziyaretçinin görmediği bir politika sürümüyle sonradan gönderilmez. Önceki bir SDK sürümü yerel kuyrukta böyle bir karar bıraktıysa bu karar düşürülür (final: true, reprompt: true içeren consent:error) ve ziyaretçiye yeniden sorulur.
• Tek istisna, data-site olmadan kullanılan local modudur: sunucuya hiçbir şey gönderilmez; bu yüzden banner gösterilir ve kararlar tarayıcıda kalır (local_only: true).
• Onay, aktif olmayan bir sürüme referans veriyorsa sunucu 409 CONFIG_OUTDATED yanıtını verir. Bkz. Yeniden onay ve değişen doküman sürümleri.

Yapmanız gereken: panelde bir çerez politikası dokümanı oluşturun, banner’ınızın kullandığı her dilde bir sürüm yayımlayın ve dokümanı siteye bağlayın.

---

Onaydan önce scriptleri engelleme

Yalnızca sizin etiketlediğiniz scriptler engellenir. SDK sayfayı izleyiciler (tracker) için taramaz ve dokunmadığınız scriptlere müdahale etmez: normal bir <script> etiketi, onay olsun ya da olmasın, hemen çalışır.

Bir scripti bekletmek için type değerini text/plain olarak değiştirin ve kategorisini belirtin:

<!-- Satır içi script: yalnızca "analytics" kategorisine izin verildikten sonra çalışır -->
<script type="text/plain" data-cookie-category="analytics">
  /* analitik kod parçası */
</script>

<!-- Harici script: src yerine data-src kullanın -->
<script type="text/plain" data-cookie-category="marketing"
        data-src="https://connect.facebook.net/en_US/fbevents.js"></script>

• Kategori adları, banner’ınızın kategori anahtarlarıyla (analytics, marketing, preferences veya kendi anahtarlarınız) eşleşmelidir. necessary olarak etiketlenen scriptler, yapılandırma yüklenmeden önce, hemen etkinleştirilir.
• Sayfaya sonradan eklenen etiketli scriptler de (SPA gezinmesi, etiket enjeksiyonu) işlenir.
• Çalışmış olan bir script durdurulamaz. Ziyaretçi, scriptleri mevcut sayfada çalışmış bir kategoriyi geri aldığında SDK o kategorinin bilinen çerezlerini siler ve varsayılan olarak sayfayı yeniden yükler (bkz. reload_on_revoke).
• Bir kategori geri alındığında SDK, banner yapılandırmanızda o kategori için listelenen çerezleri / depolama kayıtlarını ve bunlara ek olarak iyi bilinen adlardan oluşan küçük bir yerleşik listeyi siler. Bilmediği çerezler silinmez; başka alan adlarındaki üçüncü taraf çerezler de sayfanızdan silinemez.

---

Script etiketi attribute’ları

Attribute	Varsayılan	Açıklama
data-site	—	Site API anahtarı. remote modunda zorunludur; diğer modlarda da kararların sunucuya kaydedilmesi için gereklidir.
data-mode	local-fallback	Yapılandırma kaynağı: remote, local, local-fallback. Bkz. Çalışma modları.
data-language	auto	Banner dili. auto, önce <html lang> değerini, ardından tarayıcı dilini kullanır.
data-region	auto	Algılama yerine bir bölgeyi veya çerçeveyi (DE, US, gdpr, ccpa, none, …) zorlar. Bu, uyum bölgesidir (banner’ın hangi kurallara uyacağı); verinin nerede saklanacağını veya hangi API adresinin çağrılacağını belirlemez.
data-config	—	Satır içi JSON yapılandırması (local / local-fallback için).
data-debug	false	true, hata ayıklama loglarını yazdırır. Hatalar ve uyarılar her zaman konsola yazdırılır.
data-headless	false	true, hiçbir arayüz (banner, widget, “Do Not Sell” bağlantısı) oluşturmaz. Bkz. Headless mod.
data-consent-mode	panel ayarı	true / false, Google Consent Mode v2’yi zorla açar veya kapatır. Bkz. Google Consent Mode v2.
data-reload-on-revoke	panel ayarı	true / false, reload_on_revoke davranış bayrağını geçersiz kılar.
data-modules	—	Önceden yüklenecek modüller, örn. documents, preferences. Bkz. Paketler ve talep üzerine yüklenen modüller.
data-module-base	scriptin kendi klasörü	Modül dosyalarının yükleneceği temel URL. Yalnızca bu dosyalar cmp.js ile aynı yerden sunulmuyorsa gerekir.
data-api-url	HashEntry API	First-party proxy veya özel alan adı için API temel URL’si. Hesabınızın veri bölgesinin kendi API adresi varsa yapılandırma yanıtı bunu bildirir (api_base_url) ve SDK sonraki tüm çağrılarda onu kullanır; panelin ürettiği kurulum kodu da ilgili data-api-url değerini zaten içerir. Burada sizin verdiğiniz değer her zaman önceliklidir.

---

JavaScript API (window.CMP)

window.CMP, script çalıştığı anda mevcuttur. Bir şey kaydeden metotlar, sonuç nesnesi içeren bir promise döndürür; hata fırlatmazlar.

CMP.ready(() => { /* yapılandırma yüklendi, onay durumu değerlendirildi */ });

// Banner
CMP.show();                         // banner'ı açar (örn. footer'daki bir bağlantıdan)
CMP.hide();

// Kararlar — her biri Promise<ConsentResult> döndürür
CMP.accept();                       // tüm kategorilere izin verir
CMP.accept({ marketing: false });   // marketing hariç tümüne izin verir
CMP.reject();                       // yalnızca necessary
CMP.withdraw();                     // saklanan onayı geri çeker

// Durum
CMP.getConsent();                   // ConsentState veya null
CMP.hasConsent('analytics');        // boolean ("necessary" her zaman true)

// Dil
CMP.setLanguage('de');
CMP.getLanguage();
CMP.setLocale('de', { ccpa: { optOut: 'Widersprechen' } }); // tek bir dil için metinler

// Metadata: sonrasında kaydedilen her çerez onayına ve doküman onayına eklenir
CMP.setMetadata({ order_id: 'ORD-54321' });
CMP.setMetadata('customer_id', 'CUST-999');
CMP.getMetadata();

// Bölge geçersiz kılma, tema, API URL'si, yerel yapılandırma
CMP.setRegion('DE');
CMP.setTheme({ primaryColor: '#0F766E' });
CMP.setApiUrl('/hashentry-api');
CMP.getApiUrl();
CMP.setConfig({ banner_config: { /* … */ } });

// Event'ler
CMP.on('consent:given', (payload) => {});
CMP.off('consent:given', handler);

// Dokümanlar (talep üzerine yüklenir — bkz. "Doküman Onayı ve İmza")
CMP.showDocumentApproval('terms-of-service', { language: 'en' });
CMP.approveDocument('terms-of-service', { /* … */ });

CMP.withdraw()

Geri çekme işlemi; zorunlu olmayan tüm kategorileri kapatır, bu kategorilerin bilinen çerezlerini siler, Google Consent Mode’u denied olarak ayarlar, sunucuya withdrawn kararını gönderir (saklanmış bir onay varsa), saklanan onayı tarayıcıdan kaldırır ve — opt-in bölgelerinde — banner’ı yeniden gösterir. Geri alınan bir kategorinin scriptleri sayfada zaten çalışmışsa, reload_on_revoke kapalı olmadıkça sayfa yeniden yüklenir.

CMP.setLanguage(lang)

Açık olan banner’ın dilini değiştirir ve yapılandırmayı o dil için yeniden yükler; çünkü doküman sürümleri dile özgüdür: sonraki onaylar yeni dilin çerez politikası sürümüne referans verir. Banner’da o dil için çeviri yoksa, banner’ın varsayılan diline dönülür.

CMP.setMetadata(...)

Değerler birleştirilir ve sonraki her çerez kararıyla ve doküman onayıyla birlikte metadata olarak gönderilir. Sunucu, kayıt başına en fazla 30 anahtar ve yaklaşık 16 KB metadata kabul eder.

Script yüklenmeden önce API’yi çağırma

<script>
  window.__CMP_QUEUE = window.__CMP_QUEUE || [];
  window.__CMP_QUEUE.push(['setLanguage', 'de']);
  window.__CMP_QUEUE.push(['setMetadata', { order_id: 'ORD-12345' }]);
  window.__CMP_QUEUE.push(['on', 'consent:given', (p) => console.log(p)]);
</script>

Kuyruğa alınan çağrılar, SDK başladığında sırayla çalıştırılır. Bu şekilde ayarlanan dil, otomatik algılama tarafından geçersiz kılınmaz.

---

Sonuç nesneleri

ConsentResult (accept, reject, withdraw)

{
  success: true,
  consent_token: 'ct_…',
  proof_hash: '…',                 // 64 hex karakter
  created_at: '2026-10-10T10:00:00+00:00',
  idempotency_key: '…'             // kullanıcı eylemi başına bir UUID, her yeniden denemede aynısı kullanılır
}

success, yalnızca sunucu kaydı kabul ettiğinde true olur. Aksi durumda:

{
  success: false,
  consent_token: '',
  proof_hash: '',
  created_at: '…',
  error: { code: 'NETWORK_ERROR', status: 0, message: '…' },
  pending_sync: true,              // yerel kuyrukta tutulur, yeniden denenecektir
  idempotency_key: '…'
}

• error.code, sunucunun makine kodu veya aşağıdaki SDK kodlarından biridir; error.status HTTP durum kodudur (yanıt alınamadığında 0).
• pending_sync: true, kararın tarayıcıda uygulandığı ve yerel bir kuyrukta (localStorage) beklediği anlamına gelir. Bir sonraki sayfa yüklemesinde, sekme yeniden görünür olduğunda ve tarayıcı yeniden çevrimiçi olduğunda, her zaman aynı idempotency_key ile, 7 güne veya 12 denemeye kadar yeniden denenir.
• local_only: true, gönderilecek bir şey olmadığında görünür (örneğin data-site olmadan local modu).

Ziyaretçinin seçimi her durumda tarayıcıda hemen uygulanır; sonuç ise sunucuda bunun bir kaydının bulunup bulunmadığını size bildirir. İstisna COOKIE_POLICY_MISSING durumudur: karar ne saklanır ne de uygulanır.

DocumentApprovalResult

{ success: true, decision: 'accepted', consent_token: 'ct_…', proof_hash: '…', slug: 'terms-of-service', version: '2.0.0' }
{ success: false, slug: 'terms-of-service', version: '2.0.0', error: { code: 'DOCUMENT_VERSION_CHANGED', status: 409, message: '…' } }

Doküman onayları hiçbir zaman sonrası için kuyruğa alınmaz: success değeri true değilse onay kaydedilmemiştir.

---

Event’ler

Event	Payload	Ne zaman
ready	{}	Başlatma tamamlandı (yapılandırma yüklenemediğinde de).
banner:shown	{ type } veya { headless: true, reason, config }	Banner gösterildi veya — headless modda — sizin tarafınızdan gösterilmesi gerekiyor.
banner:hidden	{ reason } veya { headless: true }	Banner kapatıldı.
consent:given	{ decision, categories, source }	”Tümünü reddet” dışındaki bir karar yerel olarak saklandı.
consent:rejected	{ decision, categories, source }	”Tümünü reddet” kararı yerel olarak saklandı.
consent:changed	{ oldCategories, newCategories }	Bir karar, önceki bir kararın yerini aldı.
consent:withdrawn	{ categories, cleanedCookies }	CMP.withdraw() çağrıldı.
consent:synced	{ consent_token, idempotency_key }	Sunucu bir kaydı kabul etti (hemen veya kuyruktan).
consent:error	{ code, status, message, idempotency_key, pending_sync, final?, reprompt? }	Bir kayıt iletilemedi. final: true, kaydın atıldığı anlamına gelir.
document:approved	{ slug, version, consentId }	Bir doküman onayı kaydedildi.
document:rejected	{ slug, version }	Ziyaretçi bir dokümanı reddetti.
document:error	{ slug, version, code, status, message }	Bir doküman yüklenemedi veya onay kaydedilmedi.
scripts:activated	{ category, count }	Bir kategorinin etiketli scriptleri etkinleştirildi.
config:updated	{ content_hash }	Daha yeni bir yapılandırma, önbellekteki yapılandırmanın yerini aldı.
language:changed	{ from, to }	Dil değişti.
error	{ scope, code, status, message, … }	Yukarıdaki hatalardan herhangi biri; scope değeri config, consent, module veya document olur.

consent:given / consent:rejected, karar tarayıcıda saklandığında tetiklenir. Kararın sunucuya ulaştığını bilmeniz gerektiğinde consent:synced event’ini (veya promise sonucunu) kullanın.

---

Hata kodları

SDK’nın kendisinin ürettiği kodlar:

Kod	Anlamı
NOT_READY	Bir karar metodu, yapılandırma yüklenmeden önce çağrıldı. Metodu CMP.ready() içinde çağırın.
COOKIE_POLICY_MISSING	Siteye bağlı, yayımlanmış bir çerez politikası dokümanı yok. Banner gösterilmez, zorunlu olmayan scriptler bloklu kalır ve karar ne saklanır ne de kuyruğa alınır.
NETWORK_ERROR, TIMEOUT	API’den yanıt alınamadı (zaman aşımı: deneme başına 5 sn).
HTTP_<status>	Sunucu, makine kodu içermeyen bir hata ile yanıt verdi.
DOCUMENT_VERSION_CHANGED	Referans verilen doküman sürümü artık aktif sürüm değil; kayıt atıldı.
PENDING_EXPIRED	Kuyruktaki bir karar 7 gün içinde iletilemedi ve atıldı.
MODULE_LOAD_FAILED	Bir modül dosyası (documents veya preferences) yüklenemedi. error olayıyla da scope: "module" olarak bildirilir.
APPROVAL_TOKEN_REQUIRED	Doküman tek kullanımlık bir onay token’ı gerektiriyor ve token verilmedi (sunucu tarafından da döndürülür).
CONFIG_UNAVAILABLE	Yapılandırma yüklenemedi (error event’i üzerinden bildirilir).
UNEXPECTED_ERROR	Bunların dışındaki her şey.

Sunucunun döndürdüğü kodlar değiştirilmeden aktarılır. En önemlileri REST API sayfasında listelenmiştir — örneğin CONFIG_OUTDATED, SITE_NOT_VERIFIED, ORIGIN_NOT_ALLOWED, RATE_LIMIT_EXCEEDED, CONSENT_LIMIT_EXCEEDED, APPROVAL_TOKEN_INVALID.

Geçici sunucu yanıtları. 503 (API_KEY_LOOKUP_UNAVAILABLE, ADMISSION_UNAVAILABLE, QUEUE_OVERLOADED) ve 429 RATE_LIMIT_EXCEEDED yanıtları aynı idempotency_key ile otomatik olarak yeniden denenir; SDK, Retry-After başlığında belirtilen süre kadar bekler. Bu süre 5 saniyeden uzunsa SDK sayfa içinde beklemez: karar yerel kuyrukta kalır (pending_sync: true) ve daha sonra gönderilir. 429 TOO_MANY_INVALID_API_KEYS yanıtından sonra SDK o sayfa görüntülemesi boyunca başka istek göndermez ve kuyruktaki kararlar korunur; data-site değerini kontrol edin. Bu yanıtların hiçbiri sayfanızı etkilemez: error olayı tetiklenir ve CMP.ready() geri çağrıları yine çalışır.

Yeniden onay ve değişen doküman sürümleri

Banner ne zaman yeniden gösterilir. Saklanan onay, verildiği banner yapılandırmasının içerik hash’ini hatırlar. Banner şu durumlarda yeniden gösterilir:

• onayın süresi dolmuşsa (geçerlilik süresi panelde ayarlanır),
• banner’ın kategori / çerez yapısı değişmişse veya
• bağlı bir dokümanın yeni bir sürümü yayımlanmışsa — banner’ın reconsent_on_doc_change ayarı kapatılmadıkça; bu ayar kapalıysa yalnızca yapı değişiklikleri yeniden onayı tetikler.

Opt-in bölgesinde yeniden onay beklenirken, ziyaretçinin önceki seçimi, ziyaretçi yeniden karar verene kadar yürürlükte kalır.

Bekleyen kararlar ve değişen doküman sürümü. Bir karar iletilememişse (çevrimdışı, sayfa kapatıldı, sunucu hatası) ve yeniden denendiği sırada referans verdiği doküman sürümü artık aktif sürüm değilse, SDK:

1. önbelleği atlayarak sunucudan güncel yapılandırmayı ister;
2. sürüm değişmemişse (409’un nedeni sunucudaki soğuk önbellektir), aynı kaydı bir kez daha gönderir;
3. sürüm değişmişse kaydı atar, yerel olarak saklanan onayı kaldırır ve banner’ı yeniden gösterir (code: "DOCUMENT_VERSION_CHANGED", final: true, reprompt: true ile consent:error).

Bekleyen bir kayıt hiçbir zaman farklı bir doküman sürümüyle yeniden gönderilmez: ziyaretçi o sürümü görmemiştir.

---

Bölgeler, mevzuat profilleri ve davranış bayrakları

Ziyaretçinin bölgesi şu sırayla çözümlenir: CMP.setRegion() → data-region → yapılandırma yanıtındaki sunucu GeoIP sonucu (detected_region) → tarayıcı saat diliminden yapılan bir tahmin → banner’ın sabit mevzuat modu → en katı kurallar (GDPR). SDK hiçbir zaman üçüncü taraf bir coğrafi konum servisini çağırmaz.

Bölge	Çerçeve	Model	Davranış
AB / AEA, İsviçre	gdpr	opt-in	Banner; etiketli scriptler izin verilene kadar engellenir.
Türkiye	kvkk	opt-in	GDPR ile aynı.
Birleşik Krallık	uk_gdpr	opt-in	GDPR ile aynı (bkz. uk_analytics_exemption).
Brezilya	lgpd	opt-in	GDPR ile aynı.
Güney Afrika, Kanada, Çin, Güney Kore	popia, pipeda, pipl, pipa	opt-in	GDPR banner kuralları uygulanır.
ABD	ccpa — yalnızca etkinleştirilmişse, aksi halde gdpr	opt-out / opt-in	Bkz. ccpa_opt_out_enabled.
Bilinmiyor	gdpr	opt-in	En katı kurallar.
none (açıkça belirtilmiş)	none	—	Banner yok; tüm scriptler çalışır.

Her opt-in profilinde banner’da, “Kabul et” ile aynı görsel ağırlığa sahip bir “Reddet” butonu her zaman bulunur ve isteğe bağlı hiçbir kategori önceden seçili gelmez — banner tasarımında ne belirtilmiş olursa olsun.

Üç davranış bayrağı (panelde banner → davranış ayarları, yerel yapılandırmada banner_config.behavior) bunu değiştirir:

Bayrak	Varsayılan	Etki
uk_analytics_exemption	kapalı	Yalnızca Birleşik Krallık ziyaretçileri: analytics olarak etiketlenen scriptler karardan önce çalışabilir. Diğer tüm kategoriler yine onay gerektirir ve ziyaretçi karar verdikten sonra onun kararı geçerli olur.
ccpa_opt_out_enabled	kapalı	ABD’de olduğu algılanan ziyaretçilere opt-out modeli uygulanır: scriptler varsayılan olarak çalışır, bir “Do Not Sell or Share My Personal Information” bağlantısı gösterilir ve Global Privacy Control sinyali bir kez opt-out olarak uygulanır (consent_type: do_not_sell_opt_out). Kapalıyken ABD ziyaretçilerine opt-in banner’ı gösterilir.
reload_on_revoke	açık	Ziyaretçi, scriptleri bu sayfada zaten çalışmış bir kategoriyi geri aldığında sayfayı yeniden yükler. Yalnızca etiketleriniz onay değişikliklerine kendileri tepki veriyorsa kapatın.

---

Google Consent Mode v2

Consent Mode açıkken SDK, mevcut değillerse window.dataLayer nesnesini ve bir gtag fonksiyonunu oluşturur ve şunları gönderir:

1. başlatma sırasında gtag('consent', 'default', { …all denied…, wait_for_update: 500 }),
2. her karardan sonra ve saklanmış bir onayla yapılan her sayfa yüklemesinde gtag('consent', 'update', { … }).

Sinyal	Bu kategoriye izin verildiğinde granted olur
ad_storage, ad_user_data, ad_personalization	marketing
analytics_storage	analytics
functionality_storage, personalization_storage	preferences
security_storage	her zaman

SDK ayrıca data layer’a hashentry_consent_default ve hashentry_consent_update event’lerini gönderir.

Kurulum:

1. Panelde banner için Google Consent Mode’u açın veya script etiketine data-consent-mode="true" ekleyin.
2. HashEntry script etiketini Google etiketinizin / GTM kod parçanızın üstüne yerleştirin.
3. default komutunun, ziyaretçinin ilk sayfa görüntülemesinde Google etiketlerinden önce gelmesi gerekiyorsa data-consent-mode="true" kullanın ve cmp.js dosyasını async olmadan yükleyin. Panel ayarı yapılandırmayla birlikte gelir; yapılandırma ise ilk ziyarette eşzamansız olarak yüklenir, sonraki ziyaretlerde başlatma sırasında önbellekteki yapılandırmadan okunur.

Consent Mode yalnızca sinyal gönderir. Consent Mode tarafından kontrol edilmeyen etiketlerin, yukarıda anlatıldığı şekilde engelleme için yine etiketlenmesi gerekir.

---

Headless mod

data-headless="true" ile SDK hiçbir şey oluşturmaz. Yapılandırmayı yine yükler, etiketli scriptleri engeller, Consent Mode’u günceller ve kararları kaydeder.

CMP.on('banner:shown', ({ headless, reason, config }) => {
  if (headless) openMyBanner(config);   // reason: no_consent | expired | reconsent | withdrawn | api | opt_out
});

myAcceptButton.onclick = async () => {
  const result = await CMP.accept({ analytics: true, marketing: false });
  if (!result.success && !result.pending_sync) showError(result.error);
};

---

Çalışma modları

Mod	Yapılandırma kaynağı
remote	Yalnızca sunucu. data-site zorunludur.
local	Yalnızca sayfa (CMP.setConfig, data-config veya <script type="application/json" id="cmp-config">).
local-fallback (varsayılan)	Sunucu; sunucuya ulaşılamazsa sayfadaki yapılandırma.

Mod yalnızca yapılandırmanın nereden geleceğini belirler. data-site ayarlı olduğu sürece kararlar her modda sunucuya gönderilir. data-site olmadan local modunda kararlar yalnızca tarayıcıda tutulur (local_only: true).

Yerel yapılandırma, sunucu yanıtıyla aynı yapıyı kullanır:

<script type="application/json" id="cmp-config">
{
  "banner_config": {
    "layout": "bottom_bar",
    "theme": { "primary_color": "#2563EB", "font_family": "system", "theme_mode": "auto" },
    "behavior": { "show_widget": true, "show_reject_button": true, "show_settings_button": true },
    "categories": [
      { "key": "necessary", "required": true, "default": true },
      { "key": "analytics", "required": false, "default": false,
        "cookies": [{ "name": "_ga", "provider": "Google", "type": "cookie", "duration": "2 years" }] }
    ],
    "languages": {
      "default": "en",
      "translations": {
        "en": {
          "title": "Cookie preferences",
          "description": "We use cookies to measure how the site is used.",
          "accept_button_text": "Accept all",
          "reject_button_text": "Reject all",
          "settings_button_text": "Manage preferences",
          "save_selected_text": "Save selection",
          "modal_title": "Cookie settings",
          "always_active_text": "Always active",
          "categories": {
            "necessary": { "label": "Necessary", "description": "Required for the site to work." },
            "analytics": { "label": "Analytics", "description": "Visitor statistics." }
          }
        }
      }
    }
  }
}
</script>
<script src="https://tool.hashentry.com/cmp.js" data-site="YOUR_SITE_API_KEY" data-mode="local" async></script>

data-site tanımlıysa SDK, açılışta çerez politikası dokümanını sunucudan bir kez sorar; çünkü bir onayın bu dokümanın sürümüne referans vermesi gerekir. Bağlı bir politika yoksa banner gösterilmez (COOKIE_POLICY_MISSING). Sunucuya ulaşılamadığında da banner göstermek için sayfa yapılandırmasına documents alanını (çerez politikası ve sürümü) ekleyin.

---

Diller ve metinler

Tüm banner metinleri (başlık, açıklama, butonlar, kategori adları) banner yapılandırmasından gelir — scriptin bir parçası değildir.

SDK, kendi arayüzüne ait metinler için yalnızca İngilizce ve Türkçe olarak küçük bir yerleşik sözlükle gelir: “Do Not Sell” diyaloğu, doküman onayı butonları ve hata satırı, çerez tablosu başlıkları ve kapatma butonu. Diğer tüm dillerde, siz sağlamadığınız sürece bu metinler için İngilizceye dönülür:

CMP.setLocale('de', {
  document: { approve: 'Ich stimme zu', reject: 'Ablehnen', saving: 'Wird gespeichert…', error: 'Ihre Zustimmung konnte nicht gespeichert werden. Bitte versuchen Sie es erneut.' },
  ccpa:     { link: '…', description: '…', cancel: 'Abbrechen', optOut: 'Widersprechen' },
  cookies:  { name: 'Name', provider: 'Anbieter', type: 'Typ', duration: 'Dauer', purpose: 'Zweck', category: 'Kategorie', count: '{n} Cookies', empty: 'Keine Cookies registriert.' }
});

Bir yapılandırma, aynı anahtarları dil başına languages.translations.<lang>.sdk_texts altında taşıyabilir.

---

Paketler ve talep üzerine yüklenen modüller

Dosya	İçerik	Yüklenme
cmp.js	Çekirdek ve çerez onayı	Sizin script etiketinizle.
cmp-documents.<hash>.js	Doküman onayı (showDocumentApproval, approveDocument)	cmp.js tarafından, bu metotlardan biri ilk kez çağrıldığında.
cmp-preferences.<hash>.js	Tercih merkezi, çerez detay tablosu, “Do Not Sell” onay penceresi	cmp.js tarafından, ziyaretçi bunlardan birini ilk kez açtığında.

Hiçbir zaman ikinci bir script etiketi eklemezsiniz. Yalnızca çerez banner’ını kullanan bir site, doküman modülünü hiçbir zaman indirmez.

• Modül dosyası, cmp.js ile aynı konumdan istenir (scriptin src değerinden türetilir).
• İlk çağrıdaki kısa gecikmeyi önlemek için modülü önceden yükleyin: data-modules="documents".
• Modül gelmeden önce yapılan çağrılar yalnızca onu bekler. Modül yüklenemezse metot success: false ve error.code = "MODULE_LOAD_FAILED" ile sonuçlanır; bir sonraki çağrı yeniden dener.
• preferences modülü yüklenemezse banner, kabul ve ret düğmeleriyle ekranda kalır; error olayı scope: "module" ve code: "MODULE_LOAD_FAILED" ile tetiklenir ve bir sonraki tıklama yeniden dener. Tercih merkezini gecikmesiz açmak için modülü önceden yükleyin: data-modules="preferences".
• Dosya adı, derleme sırasında cmp.js içine gömülen bir içerik hash’i içerir; böylece cmp.js her zaman kendisiyle birlikte derlenen modülü ister.

Content Security Policy. Modül, cmp.js ile aynı origin’den bir <script> öğesiyle yüklenir; SDK ne eval ne de satır içi script kullanır. Scriptler için ihtiyacınız olan tek şey SDK origin’idir:

script-src  https://tool.hashentry.com;
connect-src https://system.hashentry.com;

• SDK, arayüzünü kendi shadow root’u içindeki <style> öğeleriyle biçimlendirir. Politikanız style-src değerini kısıtlıyorsa, stiller için 'unsafe-inline' değerine izin verin veya bir nonce kullanın: nonce’u cmp.js etiketine koyun (<script nonce="…" …>); SDK onu style öğelerine ve oluşturduğu modül script etiketine kopyalar.
• script-src 'strict-dynamic' ve cmp.js etiketinde bir nonce ile, origin listelenmeden modül scriptine izin verilir.
• Doküman onayı diyaloğu, dokümanı src içermeyen, sandbox uygulanmış bir iframe içinde gösterir; dokümanın içindeki scriptler çalışmaz.

Subresource Integrity. https://tool.hashentry.com/cmp.js, yeni bir SDK sürümü yayımlandığında yerinde güncellenir; bu nedenle bu URL üzerindeki bir integrity attribute’u bir sonraki sürümde bozulur. SRI’ye ihtiyacınız varsa, incelenmiş bir cmp.js kopyasını aynı derlemeye ait cmp-documents.*.js / cmp-preferences.*.js dosyalarıyla birlikte kendi origin’inizde barındırın ve integrity değerini kendi etiketinizde ayarlayın.

Kendi sunucunuzda barındırma. Aynı derlemeye ait cmp.js, cmp-documents.<hash>.js, cmp-preferences.<hash>.js, cmp-preferences.js ve cmp-documents.js dosyalarını tek bir klasöre kopyalayın. Modül dosyaları başka bir yerde duruyorsa data-module-base değerini ayarlayın.

---

First-party proxy

API isteklerini kendi alan adınız üzerinden göndermek için data-api-url (veya CMP.setApiUrl) değerini kendi tarafınızdaki bir yola veya URL’ye ayarlayın ve bunu, önekin altındaki yolu değiştirmeden HashEntry API’sine iletin:

<script src="https://tool.hashentry.com/cmp.js"
        data-site="YOUR_SITE_API_KEY"
        data-api-url="/hashentry-api" async></script>

# /hashentry-api/tool/v1/consents  →  https://system.hashentry.com/tool/v1/consents
location /hashentry-api/ {
    proxy_pass https://system.hashentry.com/;
    proxy_set_header Host system.hashentry.com;
    proxy_ssl_server_name on;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

İstek imzası /tool/v1/... yolunu kapsar; bu nedenle upstream isteği tam olarak bu yolla ulaşmalıdır. Kaydedilen IP adresi, HashEntry’nin gördüğü adrestir; ziyaretçinin adresinin X-Forwarded-For başlığından alınıp alınmayacağı, proxy’nin HashEntry tarafında güvenilir olarak tanımlanmış olmasına bağlıdır — buna güvenmeden önce destek ekibine danışın.

---

SDK’nın tarayıcıda sakladıkları

Ad	Nerede	Amaç
_he_consent	first-party çerez	Ziyaretçinin kararı (kategoriler, zaman damgaları, sunucu token’ı).
he_consent_token	localStorage	Aynı kararın kopyası.
he_config_cache	localStorage	Önbelleğe alınmış yapılandırma (7 güne kadar; her yüklemede arka planda yeniden doğrulanır).
he_pending_consents	localStorage	Sunucunun henüz kabul etmediği kararlar (iletilince silinir; 7 gün sonra bırakılır).
he_gpc_applied	localStorage	Bir GPC opt-out’unun bir kez uygulandığını işaretler.
he_sdk_reload	sessionStorage	SDK’nın kendi kendini güncellemesini yeniden yükleme döngülerine karşı korur.

SDK, üçüncü taraflardan font veya başka herhangi bir kaynak yüklemez.

---

Canlı Deneyin (Playground)