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.

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)​