Kullanıcı Uçları

Kullanıcı uçları, anonim bir tarayıcıyı (ya da cihazı) sizin müşteri kimliğinizle eşleştirir ve müşteriye özellik yazar. Tarayıcıda Selwise.identify() ve Selwise.setTraits() bu uçlara konuşur; mobil SDK de aynısını yapar. Hangi anlarda çağrılacağı, kimlik seçimi ve doğrulama için Kullanıcı Kimliklendirme sayfasına bakın.

Bu iki uç hız sınırı dışındadır: kimlik birleştirmenin kaybedilmesi sonraki her ölçümü bozar.

Kimlik doğrulama

Başlık varsa Origin/Referer kanalın alan adı ve doğrulanmış takma adlarıyla karşılaştırılır; başlık yoksa (ya da kanal bir uygulama kanalıysa) x-selwise-api-key ve mobile_write kapsamı aranır. Ayrıntı: Kimlik Doğrulama ve Erişim.

identify

POST /api/v1/public/sites/:siteKey/users/identify
Content-Type: application/json

curl -X POST https://api.selwise.com/api/v1/public/sites/SITE_KEY/users/identify \
  -H "Content-Type: application/json" \
  -H "x-selwise-api-key: swpk_live_..." \
  -d '{
    "externalId": "MUSTERI-1001",
    "visitorId": "VISITOR_ID",
    "sessionId": "SESSION_ID",
    "email": "ayse@example.com",
    "traits": { "plan": "premium", "sehir": "İstanbul" },
    "pageUrl": "https://magaza.com/hesabim"
  }'

Alan	Zorunlu	Açıklama
externalId	Evet	Sizin müşteri kimliğiniz. Boşluklar kırpılır, en çok 64 karakter; daha uzunu 400 verir
visitorId	Hayır	Tarayıcıdaki ziyaretçi kimliği (Selwise.getVisitorId()). Verirseniz o ziyaretçinin geçmişi müşteriye bağlanır
sessionId	Hayır	Oturum kimliği
email	Hayır	Geçerli bir e-posta adresi olmalı, yoksa tüm istek 400 olur. Adres düz metin saklanmaz: SHA-256 özeti kimliğe yazılır
traits	Hayır	Özellik nesnesi. Her anahtar bir müşteri özelliği olur
pageUrl, userAgent	Hayır	Bağlam. pageUrl yoksa Referer başlığı kullanılır

Yanıt:

{
  "success": true,
  "merged": true,
  "user": {
    "id": "0c5a8d6e-1f4b-4c0a-9b0e-7a2f5d8c3e19",
    "externalId": "MUSTERI-1001",
    "firstSeenAt": "2026-09-30T12:01:02.000Z",
    "lastSeenAt": "2026-10-09T09:12:00.000Z",
    "attributes": { "plan": "premium", "sehir": "İstanbul" }
  },
  "aliases": ["VISITOR_ID"]
}

Alan	Anlamı
success	Kimlik kaydedildi
merged	Bu çağrıda yeni bir ziyaretçi (cihaz) müşteriye bağlandıysa true. O ziyaretçinin önceki gezinmesi ve olayları profile eklenir
user.id	Selwise'in kendi (dahili) profil kimliği; sizin externalId'niz değil
aliases	Bu müşteriye bağlı tüm ziyaretçi kimlikleri

Bilmeniz gerekenler:

• Bir tarayıcı yalnızca bir kişinin birincil ziyaretçisi olabilir. Ortak bir tarayıcıda iki hesap giriş yaparsa ilki birincil ziyaretçiyi tutar, ikincisi yalnızca takma ad (alias) alır. İkisi de kimliklenir.
• E-posta izin sayılmaz. Adres, kişinin iletişim kaydına izinsiz eklenir: kişiye ulaşılabildiğini söyler, pazarlama iznini kaydetmez. İzin için Onay ve Bülten API'si uçlarını kullanın.
• Aynı çağrı tekrar edilebilir. Çağrı idempotenttir; tekrar eden bir identify yeni profil yaratmaz, lastSeenAt güncellenir. Widget aynı kişi, tarayıcı ve adres için onaylanmış ikinci çağrıyı hiç göndermez.
• Kimlik değişkenliği. Oturum kimliği gibi her girişte değişen bir değer her seferinde yeni bir müşteri yaratır.

Hatalar

Durum	Neden
400	message: "Validation failed" ve errors[]: externalId yok, email geçersiz, bilinmeyen alan. Ya da externalId 64 karakterden uzun (mesaj sınırı söyler)
403	Kod SITE_NOT_VERIFIED: kanal doğrulanmamış. Ya da Origin yetkisiz, ya da Invalid API key or insufficient scope
404	Kod SITE_KEY_NOT_FOUND: site anahtarı yanlış. Gövdede params.siteKey aranan değeri söyler
5xx	Bizim tarafımızda bir hata; 200 ve success: false ile saklanmaz, widget bu durumda kimliği yerelde tutar ve yeniden denemez

traits

POST /api/v1/public/sites/:siteKey/users/traits
Content-Type: application/json

Kimliği değiştirmeden müşteriye özellik yazar.

curl -X POST https://api.selwise.com/api/v1/public/sites/SITE_KEY/users/traits \
  -H "Content-Type: application/json" \
  -H "x-selwise-api-key: swpk_live_..." \
  -d '{ "externalId": "MUSTERI-1001", "traits": { "plan": "platinum", "sadakatPuani": 1200 } }'

Alan	Zorunlu	Açıklama
externalId	Evet	Önceden identify edilmiş müşteri kimliği
traits	Evet	Özellik nesnesi. Değerler metin, sayı, doğru/yanlış, dizi ya da nesne olabilir; tür otomatik belirlenir
visitorId	Hayır	Kabul edilir ama özelliklerin yazılacağı müşteriyi belirlemez; müşteri her zaman externalId ile bulunur

Yanıt:

{ "success": true, "updated": ["plan", "sadakatPuani"] }

updated, gönderdiğiniz her anahtarı listeler; değeri zaten aynı olan anahtar yeniden yazılmaz ama listede kalır (aynı değeri her sayfada göndermek "özellik değişti" tetikleyicisini yanlışlıkla çalıştırmaz).

Durum	Neden
400	externalId ya da traits eksik, ya da bilinmeyen alan
404	Kod SITE_USER_NOT_IDENTIFIED: bu externalId ile henüz bir müşteri yok. Önce identify çağırın, sonra özellik yazın
403	SITE_NOT_VERIFIED, yetkisiz Origin ya da yetersiz anahtar

Çıkış

Çıkış için ayrı bir uç yoktur; tarayıcıdaki kimlik, veri katmanına user_logout göndererek unutturulur: Kullanıcı Kimliklendirme. Sunucu tarafında yapılacak bir şey yoktur; profil silinmez, yalnızca sonraki olaylar o kişiye yazılmaz.

Sırada ne var

• Kullanıcı Kimliklendirme — ne zaman, hangi kimlik
• Sipariş API'si — sipariş ile aynı siteUserId
• Müşteri Profilleri — profil panelde nasıl görünür