Widget ve SDK Uçları

Bu sayfa, widget'ın ve mobil SDK'nın kendi trafiği için kullandığı uçları listeler. Çoğu entegrasyon bunlara dokunmaz: widget zaten çağırır. Kendi istemcinizi (örneğin sıfırdan bir mobil uygulama ya da bir "headless" mağaza) yazıyorsanız hangi isteğin ne işe yaradığını buradan okursunuz. Uç dizini için Public API, kimlik kuralları için Kimlik Doğrulama ve Erişim sayfasına bakın.

Deney ataması

Bir ziyaretçinin hangi deney koluna girdiğini söyler. Atama visitorId'nin özetinden hesaplanır; yani aynı ziyaretçi her seferinde aynı kolu alır ve istemci tarafında saklanması gerekmez.

GET /api/v1/public/experiments/assign?siteKey=SITE_KEY&visitorId=VISITOR_ID&p=4&capabilities=holdout,audience

Parametre	Zorunlu	Açıklama
siteKey	Evet	Kanal anahtarı (sorgu parametresi, yolda değil)
visitorId	Evet	Boşsa 400: boş bir kimlik tüm anonim ziyaretçileri aynı kovaya atardı
p	Hayır	Protokol sürümü (4 güncel). Bir kolun yer tutucusu ya da koşulu istemcinin sürümünün üstündeyse ziyaretçi o deneyin tüm kollarının dışında tutulur
capabilities	Hayır	İstemcinin uygulayabildikleri, virgülle ayrılmış: holdout (kontrol kolu hiçbir şey çizmez), audience (kolun kendi kitle kurallarını istemci değerlendirir). Bildirmeyen istemci bunu gerektiren deneylerin dışında kalır
forceVariant	Hayır	QA için deneyId:kolId, tekrarlanabilir. Hash'i ve trafik payını atlar; widget zorlanan kol için hiçbir sayı yazmaz

Yanıt, deney kimliğine göre anahtarlanmış bir nesnedir; her değer experimentId, variantId, variantName, experimentMode ve duruma göre isForced, holdout, hasHoldout, liveCartRequired, audience alanlarını taşır. Hız sınırı IP başına dakikada 60. Kimlik: yalnızca doğrulanmış kanal (403 aksi hâlde).

Deney sayaçları

POST /api/v1/public/experiments/track?siteKey=SITE_KEY
POST /api/v1/public/experiments/track-event?siteKey=SITE_KEY

track gövdesi: experimentId (UUID), variantId (UUID), eventType (exposure, impression, conversion, goal), goalId (UUID, goal için), visitorId (en çok 200 karakter; yoksa olay sayılır ama istatistiğe girmez), revenue, testMode. Yanıt { "success": true }; testMode: true ise { "success": false, "reason": "test_mode" } ve olay sayılmaz. Bir varyant kanalın çalışan bir deneyine ait değilse yazım reddedilir (success: false); bir kanalın anahtarıyla başka kanalın deneyi şişirilemez. Dakikada 120 istek.

track-event serbest bir deney olayıdır: { visitorId, eventName, data }.

Segment değerlendirme

Bir ziyaretçinin hangi segmentlerde olduğunu söyler; widget segment hedefli kampanyaları göstermeden önce bunu sorar.

POST /api/v1/public/segments/evaluate

Gövde: segmentIds (UUID dizisi, zorunlu), visitorId (en çok 100), siteUserId (en çok 255), siteUserProfileId (UUID), sessionId, deviceType (desktop, mobile, tablet), referrer, pageUrl. Kanalı siteKey sorgu parametresiyle söyleyin (?siteKey=SITE_KEY). Yanıt { "results": { "<segmentId>": ... } }. Dakikada 120 istek.

Kimlik kanıtlanmadan sorulamaz: siteUserId mağazanızın ardışık olabilen müşteri kimliğidir ve segment kimlikleri herkese açık yapılandırmada yer alır; bağlama olmasaydı herkes numaralandırılmış müşterilerin "terk edilmiş sepet" ya da "yüksek değerli" üyeliğini okuyabilirdi. Bu yüzden iddia edilen kimlik, identify ile o ziyaretçi için kurulmuş olana indirgenir; kanıtlayamayan çağıran hata almaz, ziyaretçi kapsamlı bir cevap alır.

Senaryo gelen kutusu

Bir senaryonun site içi teslimatı, ziyaretçi sonraki sayfayı yüklediğinde widget tarafından toplanır. config yanıtındaki scenarios.enabled true değilse çağırmayın.

GET  /api/v1/public/sites/:siteKey/scenarios/inbox?visitorId=VISITOR_ID&p=4
POST /api/v1/public/sites/:siteKey/scenarios/inbox/ack

inbox yanıtı { "entries": [ ... ] } biçimindedir. Her giriş deliveryId, scenarioId, runId, nodeId, campaignId, tokens, respectFrequencyCaps, expiresAt, available, scenarioOnly ve (yalnızca senaryoya özel kampanyalarda) kampanyanın kendisini (campaign) taşır. Giriş sayısı sınırlıdır. İstemcinin p protokolü bir kampanyayı çizmeye yetmiyorsa o giriş yanıtta yer almaz ve beklemede kalır; kapatılmaz.

ack gövdesi: visitorId ve en çok 20 öğelik acknowledgements, her biri deliveryId (UUID) ve outcome (shown ya da suppressed:<neden>). shown teslimatı kapatır, başka her sonuç nedeniyle birlikte "atlandı" olarak kapatır. Yanıt { "updated": 1 }. Bilinmeyen kimlik hata vermez, sayılmaz. Her iki uç da dakikada 60 istek ve doğrulanmış kanal (alan adı ya da anahtar) ister. Bu yanıt config'in önbelleğine asla girmez: ziyaretçiye ait claim'ler herkese dağıtılmasın diye ayrı bir istektir.

Tarayıcı bildirimi aboneliği

POST /api/v1/public/sites/:siteKey/push/subscribe
POST /api/v1/public/sites/:siteKey/push/unsubscribe

subscribe gövdesi tarayıcının PushSubscription'ından gelir: visitorId (en çok 64), siteUserId (isteğe bağlı, en çok 64), endpoint (en çok 2000), p256dh ve auth (en çok 255). unsubscribe yalnızca endpoint ister. İkisi de { "success": true } ya da { "success": false } döner ve dakikada 60 istekle sınırlıdır. Kanalda bildirim anahtar çifti yoksa abonelik kabul edilmez (success: false); aksi hâlde ziyaretçi, hiçbir şeyin kullanamayacağı bir izin için tarayıcının tek hakkını harcamış olurdu.

Bu uç, ziyaretçi bildirim iznini verdikten sonra widget'ın çağırdığı uçtur. İzni isteyen yöntemler Selwise.requestPushPermission() ve onu çağıran bir düğmedir: JavaScript API. Bildirimi gösteren service worker'ı sitenizin kök dizininde yayınlamanız gerekir; bkz. Widget Kurulumu.

Abonelikten çıkış bağlantıları

GET  /api/v1/public/sites/:siteKey/unsubscribe?t=TOKEN
POST /api/v1/public/sites/:siteKey/unsubscribe?t=TOKEN
POST /api/v1/public/sites/:siteKey/unsubscribe/resubscribe?t=TOKEN

Selwise'in gönderdiği her e-postadaki bağlantıdır. GET bir HTML sayfası döndürür (Cache-Control: no-store) ve bilinmeyen bir belirteç için bile 200 verir: 404 hangi belirteçlerin gerçek olduğunu gösterirdi. POST RFC 8058 tek tıkla çıkıştır ve { "success": true } ya da false döner. resubscribe aynı belirteçle yeniden abone eder. Dakikada 60 istek. Belirteç tahmin edilemeyen bir HMAC'tir ve yalnızca bu tek işi yapar. Bir yeniden abonelik, bir bounce ya da şikâyet baskısını kaldırmaz; sayfa bunu söyler.

Sağlayıcı olayları

POST /api/v1/public/messaging/:siteKey/:providerId/events

Mesaj sağlayıcınızın (bounce, şikâyet, açılma, tıklama) webhook'u için bir alıcıdır; sağlayıcının kendi imzasıyla doğrulanır, doğrulanamayan çağrı işlenmeden atılır. Her zaman 200 ve { "received": true } döner: başka bir durum sağlayıcının günlerce yeniden denemesine yol açardı. Dakikada 600 istek. Kurulumu: Mesajlaşma Sağlayıcıları.

Görsel editör

/public/sites/:siteKey/editor/verify, .../editor/sessions/:sessionId (GET), .../draft (PUT) ve .../result (PUT) uçları panelin görsel yerleştirme ve sayfa üstü deney editörü içindir. Editör yalnızca panelden açılan, doğrulanmış bir belirteçle gelen yöneticiye yüklenir; bir alışverişçi bu uçlara hiç ulaşmaz. Dakikada 10 ile 240 arası sınırları vardır. Entegrasyonunuzun çağıracağı bir şey değildir: Görsel Yerleştirme.

Yüklenen medya

GET /api/v1/public/media/:assetKey

Panelden yüklediğiniz görselleri (kampanya görselleri, marka logosu) yayınlar. Kimlik istemez; Content-Type ve Content-Length doğru gelir ve Cache-Control: public, max-age=31536000, immutable ile bir yıl önbelleğe alınır. Yüklenen her dosyanın kendi rastgele assetKey'i vardır ve adres immutable işaretlidir: bir adresin içeriği değişmez, güncel görsel her zaman yeni bir yüklemenin yeni adresidir. Bu adresler img-src için api.selwise.com'a izin verilmesini gerektirir: Widget Kurulumu.

Kullanımdan kalkan uçlar

Uç	Durum
GET /public/sites/:siteKey/widgets	Widget'lar Eylül 2026'da kampanyalara birleşti. Her zaman { "widgets": [] }. Eski bir client.js hâlâ çağırdığı için duruyor
config yanıtındaki widgets	Aynı sebep; her zaman boş dizi
/public/newsletter, /public/newsletter/subscribe, /public/newsletter/confirm (siteKeysiz)	Selwise'in kendi tanıtım sitesi bülteni; sizin kanalınızın ucu değil

Sırada ne var

• Public API — uç dizini
• Kimlik Doğrulama ve Erişim
• Mobil SDK — bu uçları sizin yerinize çağıran hazır istemci