Event Takibi

Mobil uygulamada ekran adlandırma, olay gönderme ve sipariş bildirme. Kimlik, onay ve kuyruk ayrı bir sayfadadır: Kimlik, Onay ve Kuyruk.

Ekran adları

Web'de sayfa hedefleme URL'e dayanır; uygulamada URL yoktur. Her ekran için tek ve sabit bir sentetik değer kullanın ve ekrana girildiğinde bildirin:

selwise.trackScreenView('app://home');       // bağlamı kurar ve page_view gönderir
selwise.setScreen('app://product');          // yalnızca bağlamı kurar, olay göndermez

setScreen o andan sonra kuyruğa alınan her olaya ekran adını işler; kuyruk ekran değişiminde yeni bir istek açar, böylece bir parti hiçbir zaman iki ekranı karıştırmaz. trackScreenView sepet bildirilmişse page_view üstverisine cartSource: host ekler; Channel Overview ekranındaki Cart value kartı bu damgayla sepetin ölçülüp ölçülmediğini söyler.

Panelde hedefleme nasıl eşleşir

Kampanya ve öneri şeridinin Page targeting alanındaki desenler ekran adına şöyle uygulanır:

Desen	Eşleşme
app://product	Ekran adı bu değere eşit veya bu değeri içeriyor (app://product-list de eşleşir)
app://account/*	* joker olarak çalışır; tüm ifadeyle eşleşmelidir
regex:^app://product$	Düzenli ifade, büyük/küçük harf duyarlı, en çok 500 karakter

Katı eşleşme istiyorsanız regex: kullanın. Aynı kural excludeUrls için de geçerlidir. Sayfa türü (home, product, category, search, checkout, cart, account, other) kuralı ise ekranı yalnızca siz bildirirseniz çalışır: getSurfaces(url, { pageType: 'product' }). Bildirmezseniz sayfa türü kuralı açık kalır, yani kampanya her ekranda görünür. Ayrıntı: Kampanya ve Widget.

Olay gönderme

track(name: string, options?: TrackOptions): void

interface TrackOptions {
  entityType?: EntityType;          // varsayılan: 'custom'
  entityId?: string;
  productItemCode?: string;         // besleme item_code ile aynı olmalı
  metadata?: Record<string, string | number | boolean | null>;
  timestamp?: number;               // ms; varsayılan şu an
  correlationId?: string;
  parentEventId?: string;
}

track() asla hata fırlatmaz ve ağı beklemez; render sırasında ya da dokunma işleyicisinde güvenle çağırılır. Olay kuyruğa girer ve arka planda gönderilir.

selwise.trackProductView('SKU-12345');
selwise.trackAddToCart('SKU-12345', { quantity: 1, price: 749.9, currency: 'TRY' });
selwise.trackRemoveFromCart('SKU-12345');

selwise.track('checkout_begin', {
  entityType: 'checkout',
  metadata: { total: 1499.7, currency: 'TRY', itemCount: 3 },
});

Kısayollar product_view, add_to_cart ve remove_from_cart olaylarını entityType: 'product' ile gönderir; ikinci parametre metadata'dır. quantity ya da price gibi alanlar TrackOptions'ın kendisinde değil, metadata içinde verilir.

Kurallar:

• Olay adı kanonik olmalı. Sunucu kanonik bir olay sözlüğünü tanır (Event Referansı); tanımadığı ad custom_event'e dönüştürülür ve sizin adınız kaybolur. Kendi olayınız için track('custom_event', { metadata: { eventName: 'kupon_kullanildi' } }) yazın.
• metadata düz olmalı: değerler yalnızca metin, sayı, boolean ve null olabilir; olay başına serileştirilmiş boyut en çok 2 KB'tır. Sınırı aşan tek bir olay partinin tamamının 400 ile reddedilmesine yol açar ve SDK, 408 ile 429 dışındaki 4xx yanıtları kalıcı sayıp partiyi yeniden denemeden siler.
• Ürün kodu besleme ile aynı olmalı. itemCode, ürün beslemenizdeki item_code değeridir (çoğu katalogda varyant SKU'su). Eşleşmezse ürün bazlı raporlar ürünü düşürür. Sepet kodunu (cartCode) ya da grup kodunu (groupCode) kimlik diye göndermeyin. Bkz. Varyant Gruplama.
• entityType değerleri: campaign, widget, enrichment, recommendation, search, script, page, product, basket, checkout, user, custom.

SDK'nın kendiliğinden gönderdikleri

Çağrı	Gönderilen olay (entityType)
trackScreenView	page_view (page)
identify	identify (user), yalnızca kullanıcı değiştiyse
trackSurfaceView / trackSurfaceClick / dismissSurface	impression / click / close (campaign)
trackGoalReached	goal_reached (campaign)
trackRecommendationImpression / trackRecommendationClick	widget_impression / product_click (recommendation)
search	search_query ya da search_zero_results (search)
trackSearchClick	product_click (search)
trackEnrichmentView / trackEnrichmentClick	impression / click (enrichment)
subscribeNewsletter	user_signup (campaign ya da custom)

Sipariş

Ciro atfı siparişten okunur; her tamamlanan sipariş için trackOrder çağrılmalıdır. track()'ten farklı olarak beklenir: kayıp bir sipariş kayıp bir ciro atfıdır.

trackOrder(order: OrderInput): Promise<{ success: boolean; created: boolean; id?: string }>

const { created } = await selwise.trackOrder({
  orderId: 'ORDER-2026-1881',        // tekilleştirme anahtarı
  total: 1499.7,
  currency: 'TRY',
  items: [
    { productItemCode: 'SKU-12345', quantity: 1, unitPrice: 749.9 },
    { productItemCode: 'SKU-67890', quantity: 2, unitPrice: 374.9 },
  ],
});

Alan	Not
orderId	Zorunlu. Aynı değerle tekrar göndermek siparişi ikiye katlamaz (created: false döner).
total	Zorunlu. Alt toplam, indirim, kargo ve vergi için subtotal, discountTotal, shippingTotal, taxTotal isteğe bağlıdır.
currency	ISO 4217. Vermezseniz sunucu kanalın para birimini kullanır; yanlış tahmin yerine bilerek boş bırakılır.
items[]	productItemCode (besleme item_code), name, quantity, unitPrice, totalPrice, metadata.
status, placedAt, metadata	İsteğe bağlı.

trackOrder önce kuyruğu gönderir (son tıklama atfı sipariş öncesi tıklamayı görsün diye), sonra siparişi deviceType: mobile_app ile yollar. Hata durumunda SelwiseApiError fırlatır; 403 çoğunlukla anahtarda mobile_write olmamasıdır, 429 IP başına dakikada 10 sipariş sınırıdır. Siparişi hem WebView köprüsünden hem kendi kodunuzdan bildirirseniz aynı orderId'yi kullanın: WebView Köprüsü. Ayrıntı: Sipariş Takibi.

Sırada ne var

• Kimlik, Onay ve Kuyruk
• Kampanya ve Widget