Consent SDK — Entegrasyon Dokümanı

Bu paket, Consent SDK'nın entegrasyonu için 3. parti geliştiricilere özel basitleştirilmiş sözleşme setidir.

İçerik, SDK'ın çalışması için sizi ilgilendiren kısımları (endpoint'ler, istek/yanıt formatları, karar mantığı) sade ve net dille açıklar. Geliştirme tarafındaki iç detaylar, arşiv notları ve doğrulama araçları bu pakette yer almaz — yalnızca entegrasyon için gereken sözleşme taşıyan.

Okuma sırası: Bu dosya → 00-auth → 01-config → 02-postconsent. Üç sözleşme, sırayla okunduğunda uygulamanın açılışından onay kaydına kadar olan kapalı döngüyü birlikte tamamlar.

1. Bu SDK ne yapar?

SDK, mobil uygulamanızda (veya web tarafında) kullanıcıdan açık rıza (açık izin) alır; rızayı sunucuya kaydeder ve onayın sonucunu uygulamanızdaki ölçüm/analitik ve reklam etiketlerine (tag) uygular.

Tek bir akış üzerinde çalışır. Acaba "şu an ne yapmalıyım?" sorusu, her açılışta sunucudan gelen karar bloğuyla çözülür:

        (uygulama açılıyor)
                  │
                  ▼
   ┌─────────────────────────────┐
   │ 00 · AUTH                    │
   │  "Kimim, neyi biliyorum?"    │
   │  Kimlik + cihaz durumu      │
   │  ─────────────────────────►  │
   │  Yanıt: versiyonlar + token   │
   │        + decision (karar)    │
   └──────────────┬──────────────┘
                  │ decision.updateRequired ?
                  ▼
   ┌─────────────────────────────┐
   │ 01 · GET /config             │
   │  "Güncel ayarlar neler?"     │
   │  Token ile tam config çek    │
   │  ─────────────────────────►  │
   │  Yanıt: banner/manager       │
   │  + tüm grup & metinler       │
   └──────────────┬──────────────┘
                  │ Kullanıcı ekranda seçim yapar
                  ▼
   ┌─────────────────────────────┐
   │ 02 · POST_CONSENT            │
   │  "Kullanıcı bunları seçti"   │
   │  Onay eylemini kaydet       │
   │  ─────────────────────────►  │
   │  Yanıt: kayıt + yeni durum   │
   └──────────────┬──────────────┘
                  │ Onay sonucunu etiketlere uygula
                  ▼
        [ Bir sonraki açılış: 00 AUTH ]
        └──────────────────► DÖNGÜ KAPALI

Bu üç adım birbirine zincirlidir: AUTH'ın verdiği token config adımında kullanılır; config adımı üretilen onay, POST_CONSENT'te kaydedilir; POST_CONSENT'in döndürdüğü cihaz durumu (localState) bir sonraki açılıştaki AUTH'a geri beslenir. Hiçbir adım bir öncekinin çıktısını kaybetmez.

2. Üç sözleşme — Ne işe yarar?

Adım	Dosya	Ne yapar	Ne zaman çalışır
00	`00-auth.md`	Uygulama kimliğini doğrular, güncel versiyonları ve bir token döndürür; açılışta ne yapılacağına dair karar verir	Her uygulama açılışında (her seferinde)
01	`01-config.md`	AUTH'un verdiği token ile tam config'i (tema, ekranlar, gruplar, metinler) sunucudan çeker	AUTH'un kararında config yenileme gerekli olduğunda
02	`02-postconsent.md`	Kullanıcının onay seçimini (`accept_all` / `reject_all` / `modify`) sunucuya kaydeder; onayın etiketlere uygulanmasını tanımlar	Kullanıcı onay ekranında bir seçim yaptığında

Kritik tasarım kararları (bunları bilmek entegrasyonu belirler):

İki aşamalı açılış: AUTH hafif tutulur — yalnızca versiyonlar + token + karar döner. Tam config (büyük gövde) yalnızca değiştiğinde çekilir. İçerik değişmiyorsa (%95 açılış) config hiç transfer edilmez → açılış hızlı, veri ve gecikme tasarrufu.
Token = oturum kimliği: AUTH bir token üretir. Bu token, tokenExpiresIn (varsayılan 300 sn = 5 dk) penceresi boyunca hem config okumada hem onay kaydında geçerlidir. Okuma (config) token'ı tüketmez; yalnızca onay kaydı (POST_CONSENT) oturumu kapatır/tüketir. Süre dolunca token ölür → yeniden AUTH yapılır.
Retrigger (tekrar sorma) geri beslemesi: Cihazda saklanan localState her açılışta gönderilir. Sunucu, içerik veya şema değiştiyse reprompt üretir; yalnız görsel (uiVersion) değiştiyse reprompt yok (sadece görünüm yenilenir).
Onay grup seviyesindedir: Kullanıcı onayı 4 kategori-gruba aittir: essential (zorunlu), functionality (işlevsellik), targeting (hedefleme/reklam), tracking (analitik). Bir grup onaylanınca/onaylanmayınca, o gruba bağlı etiketlerin tümü birlikte açılır/kapanır.
Durum yalnız iki değer: granted (açık) veya denied (kapalı). Ara durum yoktur.

3. Hızlı Başlangıç

Entegrasyonu adım adım özetler; detay her dosyanın içinde.

00-auth.md'yi oku. Her açılışta POST …/auth isteğini nasıl kuracağını (kimlik + localState), HMAC imza/güvenlik modelini ve yanıtta gelen decision'ı nasıl değerlendireceğini öğren.
01-config.md'yi oku. decision.updateRequired === true ise token ile POST …/config isteği atıp tam config'yi parsel ederek onay ekranını (banner/manager/detail) kura. Token'ın burada tüketilmediğini (tokenConsumed: false) bil → aynı token ile onaya geçeceksin.
02-postconsent.md'yi oku. Kullanıcı bir seçim yaptığında POST …/consent isteğini kur. Yanıtta gelen onay haritasını etiketlerine uygulayacak dağıtım (mapping) mantığını ve cihaz durumunu (localState) önbelleğe yazıp döngüyü kapalı tutacağını öğren.

Her adımda offline/hata davranışı da belgelenmiştir: bağlantı yoksa kullanıcı boşta bırakılmaz (bundled config + arka plan denemesi).

4. Ortak Kurallar

Üç sözleşmenin tamamında geçerli olan, bilmek için tek yerde topladığımız kurallar:

Kural	Açıklama
Transport	Üç çağrı da `POST`'tur. `{{SDK_BASE_URL}}` + path (`/v2/consent/{consentId}/…`). Gövde `application/json` (UTF-8).
Neden POST (GET değil)? Tutarlı tek transport + ara katmanlarda (proxy/CDN) önbellekleme riski yok. Adımlardaki "GET /config" okuma semantiğidir, HTTP fiilini değil.
Timeout	Her istekte `15` sn.
`camelCase`	Tüm alan adları camelCase.
Hata envelope'u	Hatalarda ortak gövde döner: `{ success, code, message, retryable, requestId }`. `message` teşhis metnidir, UI'da gösterilmez (kullanıcıya gösterilecek metin config'in `localization` bloğundan gelir). Her sözleşmenin kendi hata kodu tablosu vardır.
Kimlik	`consentId` hem path'te hem gövdededir; sunucu path ↔ gövde ↔ token üçlüsünü çapraz doğrular.

5. Onay → Etiket (Analytics/Reklam) Dağıtımı

Onayın gerçek etkisi, kullanıcı tercihinin uygulamanızdaki etiketlere (GA4, Google Ads, Meta Pixel vb.) uygulanmasıdır. Bu dağıtımın sorumluluğu SDK/entegrasyon tarafındadır; sunucu yalnız grup kimliği ve son durumunu döndürür.

Config'deki her grup, bir consentKeys[] listesi taşır → bu key'ler etiketlerinizi temsil eder.
Kullanıcı bir grubu açınca/kapayınca, SDK o grubun tüm consentKey'lerini birlikte granted/denied yapar ve etiketlere iletir.
essential (→ security_storage) her zaman granted'tir ve kullanıcı kapatamaz (kilitli).
Etiketlere iletim iki eşdeğer yoldan biriyle yapılır: GA4 gtag('consent', …) veya GTM dataLayer.push({ consent: … }). Seçim projenize aittir; mantık ikisinde de aynıdır.

Bu dağıtımın detayı, örnekleri ve security_storage'ın neden her zaman açık kaldığı 02-postconsent.md içinde anlatılmıştır (bölüm 6).

6. iOS Katmanı (ATT) — Kısa Not

iOS'ta reklam/hedefleme takibi, kullanıcının cookie/consent onayının yanında işletim sisteminin ATT (App Tracking Transparency) iznini de gerektirir. Yani targeting grubu için hem kullanıcı onayı hem sistem ATT authorized birlikte olmalıdır; ikisi AND ile birleşir.

Bu davranış, ana akışın (AUTH → config → onay) yan dallarıdır; onay sözleşmelerinin içine gömülü değildir. iOS tarafı detayı, ATT'nin dört durumluk modelini, ne zaman sistem prompt atanacağını ve sonuçların etiketlere nasıl yansıtılacağını 02-postconsent.md bölüm 7'de (kısaca) ve ihtiyacınız olduğunda ek referansta bulabilirsiniz. Android'de ATT karşılığı yoktur — bu katman devredışıdır (attention: null).

7. Paket İçeriği

Kılavuzlar (`.md`)

Dosya	İçerik
`README.md`	Bu dosya — sistem haritası, kararlar, hızlı başlangıç, ortak kurallar
`00-auth.md`	AUTH sözleşmesi: akış, güvenlik (HMAC/imza), retrigger kararı, hata & offline
`01-config.md`	GET /config sözleşmesi: token ile config çekme, token yaşam döngüsü, hata & offline
`02-postconsent.md`	POST_CONSENT sözleşmesi: onay eylemi, doğrulama, hata + onay→etiket dağıtımı + iOS ATT katmanı

Örnek Payload'lar (`.json`)

Her sözleşme için doldurulmuş, gerçekçi placeholder kimlikli istek/yanıt örnekleri. .md dosyalarındaki inline örneklerle birebir aynıdır; ayrıca .json dosya olarak da dahil edildi ki 3. party isterse doğrudan referans/request olarak kullanabilsin.

Dosya	Karşılığı
`00-auth.request.json`	İlk açılış isteği (placeholder kimlik + boş `localState`)
`00-auth.response.json`	AUTH yanıtı (versiyonlar + token + decision)
`01-config.request.json`	GET /config isteği (minimal gövde; token `X-Consent-Token` header'ında taşınır)
`01-config.response.json`	GET /config yanıtı (envelope + tam config gövdesi)
`02-postconsent.request.json`	Onay kaydı isteği (`modify` + karma `consent` map)
`02-postconsent.response.json`	Onay yanıtı (`consent` map + `localState`)

Örneklerdeki kimlik değerleri (sk_live_…, ck_…, cfg_t_…, cr_…) placeholder'dır — üretimde kendi konsolunuzdan gelen karşılıkları kullanın.

Bu doküman size yardımcı oldu mu?

Değerlendirmeniz, dokümanı geliştirmemize yardımcı olur.

Değerlendirme yapmak için giriş yapmalısınız.

Destek soruları ve yorumlar

Bu dokümanla ilgili soru sorabilir veya deneyiminizi paylaşabilirsiniz.

1. Bu SDK ne yapar?​

2. Üç sözleşme — Ne işe yarar?​

3. Hızlı Başlangıç​

4. Ortak Kurallar​

5. Onay → Etiket (Analytics/Reklam) Dağıtımı​

6. iOS Katmanı (ATT) — Kısa Not​

7. Paket İçeriği​

Kılavuzlar (.md)​

Örnek Payload'lar (.json)​