# Event Referansı Tüm canonical eventler ve payloadları Kaynak: https://selwise.com/docs/integration/events Selwise'ın tüm analitiği (huniler, yolculuklar, kohortlar, ilişkilendirme) tek bir **kanonik event** sözlüğü üzerine kuruludur. Bu sayfa, sistemin desteklediği **her event'i** tek tek, üretim yöntemi, tam payload'ı ve kod örnekleriyle açıklar. ## Event nasıl üretilir Bir event üç yoldan biriyle oluşur: 1. **Otomatik** — Client script; widget gösterimi/tıklaması, arama ve öneri etkileşimlerini kendiliğinden yakalar. 2. **Veri katmanı** — Ticari ve sayfa olayları `window.selwiseLayer.push()` ile gönderilir. Bkz. [Veri Katmanı](/docs/integration/data-layer). 3. **Manuel** — Herhangi bir event'i doğrudan `window.Selwise.track()` ile gönderirsiniz. `track()` imzası: ```ts window.Selwise.track( name: string, // kanonik event adı (bu sayfadaki başlıklar) args?: { entityType?: string; // product | page | basket | checkout | search | user | widget | campaign | recommendation | script | custom entityId?: string; // ürün için stok kodu (productItemCode); widget/kampanya için UUID metadata?: Record; // olaya özel alanlar (event başına 2 KB sınırı) } ): void ``` Script `async` yüklendiği için çağrıları güvenle sarın: ```js function selwiseTrack() { if (window.Selwise) { window.Selwise.track.apply(window.Selwise, arguments); } } ``` > **Kategoriler neden önemli** > > Her kanonik event bir **kategoriye** aittir: `page`, `commerce`, `search`, `engagement`, `recommendation`, `user`, `system`. Huniler, ilişkilendirme ve raporlar event'leri bu kategorilere göre gruplar. Aşağıdaki bölümler bu kategorilere göre düzenlenmiştir. ## Eksiksiz ölçüm için çekirdek set Aşağıdaki set, sitenizin hunisinin (görüntüleme → sepet → ödeme → satın alma) ve gelir ilişkilendirmesinin tamamı için **yeterlidir**. Bu beş event doğru gönderiliyorsa temel analitik çalışır; kalan event'ler zenginleştirmedir. ```js selwiseTrack('product_view', { entityType: 'product', entityId: 'SKU-123', metadata: { price: 749.9, currency: 'TRY' } }); selwiseTrack('add_to_cart', { entityType: 'product', entityId: 'SKU-123', metadata: { price: 749.9, quantity: 1, currency: 'TRY' } }); selwiseTrack('cart_view', { entityType: 'basket', metadata: { itemCount: 3, total: 1499.7, currency: 'TRY' } }); selwiseTrack('checkout_begin', { entityType: 'checkout', metadata: { total: 1499.7, currency: 'TRY', itemCount: 3 } }); // purchase için trackOrder önerilir — bkz. Sipariş Takibi ``` > **productItemCode besleme SKU'su ile aynı olmalı** > > Ürün olaylarında `entityId` (veya `metadata.productItemCode`), ürün beslemenizdeki stok koduyla **birebir aynı** olmalıdır. Eşleşmezse event sunucuda `degraded` işaretlenir ve ürün bazlı raporlar/öneriler boş kalır. --- ## Sayfa olayları (page) ### page_view Klasik sayfa görüntüleme. **Üretim:** otomatik (script yüklendiğinde) / veri katmanı / manuel. ```js selwiseTrack('page_view', { entityType: 'page', metadata: { type: 'home', title: document.title, path: location.pathname }, }); ``` Veri katmanı karşılığı: ```js window.selwiseLayer.push({ event: 'page_view', page: { type: 'home', title: 'Anasayfa', path: '/' }, }); ``` `type` değerleri: `home`, `product`, `category`, `search`, `checkout`, `cart`, `account`, `other`. Otomatik takip açıkken sayfa tipi URL kalıplarından tespit edilir. ### virtual_page_view SPA (tek sayfa uygulaması) yönlendirmelerinde sanal sayfa görüntüleme. **Üretim:** otomatik (`pushState`/`popstate` yakalanır) / manuel. Klasik sunucu render'lı sitelerde elle göndermeniz gerekmez; React/Vue gibi SPA'larda otomatik yakalanır. Gerekirse: ```js selwiseTrack('virtual_page_view', { entityType: 'page', metadata: { path: '/urun/sku-123', title: 'Ürün Adı' }, }); ``` --- ## Ticari olaylar (commerce) E-ticaret hunisinin belkemiği. ### category_view Kategori/liste sayfası görüntüleme. **Üretim:** manuel / veri katmanı. ```js selwiseTrack('category_view', { entityType: 'page', metadata: { category: 'Elektronik > Kulaklık', itemCount: 42 }, }); ``` ### product_view Ürün detay görüntüleme. **Üretim:** manuel / veri katmanı / otomatik (ürün sayfası tespit edilirse). ```js selwiseTrack('product_view', { entityType: 'product', entityId: 'SKU-12345', // = feed'deki item_code metadata: { productItemCode: 'SKU-12345', name: 'Kablosuz Kulaklık', price: 749.9, currency: 'TRY', category: 'Elektronik > Kulaklık', brand: 'Marka', variant: 'Siyah', inStock: true, }, }); ``` Veri katmanı karşılığı (`sku` zorunludur): ```js window.selwiseLayer.push({ event: 'product_view', product: { sku: 'SKU-12345', title: 'Kablosuz Kulaklık', price: 749.9, currency: 'TRY' }, }); ``` ### product_impression Ürünün bir listede/vitrinде görünmesi. **Üretim:** otomatik (öneri/arama listelerinde) / manuel. Kendi liste sayfanızda ölçmek isterseniz, ürün kart görünür olduğunda gönderin (IntersectionObserver önerilir): ```js selwiseTrack('product_impression', { entityType: 'product', entityId: 'SKU-12345', metadata: { position: 3, listName: 'category_grid' }, }); ``` ### product_click Bir listeden ürüne tıklama. **Üretim:** otomatik (arama/öneri sonuçlarında). Kendi listenizde: ```js selwiseTrack('product_click', { entityType: 'product', entityId: 'SKU-12345', metadata: { position: 3, listName: 'category_grid' }, }); ``` ### product_dwell_time Ürün sayfasında geçirilen süre. **Üretim:** otomatik (ürün takip modülü açıkken). Elle göndermeniz genellikle gerekmez. ### add_to_cart Sepete ekleme — hunideki en kritik dönüşüm sinyali. **Üretim:** manuel / veri katmanı / otomatik (widget'tan sepete ekleme tıklamaları). ```js selwiseTrack('add_to_cart', { entityType: 'product', entityId: 'SKU-12345', metadata: { productItemCode: 'SKU-12345', price: 749.9, quantity: 1, currency: 'TRY', }, }); ``` Veri katmanı karşılığı (birden çok ürün destekler): ```js window.selwiseLayer.push({ event: 'add_to_cart', basket: { step: 'add', currency: 'TRY', products: [{ sku: 'SKU-12345', quantity: 1, price: 749.9 }], }, }); ``` Widget, sepete eklemenin yapıldığı sayfanın türünü `metadata.pageType` olarak kendisi ekler: ürün sayfasında yapılan bir ekleme `product` taşır. Bunun için veri katmanının o sayfada sayfa görüntülemesini kaydetmiş olması yeterlidir. Kendi `pageType` değerinizi gönderirseniz o kullanılır. Raporlardaki **Ürün sayfası sepete ekleme oranı** bu alanla ölçülür. ### remove_from_cart Sepetten çıkarma. **Üretim:** manuel / veri katmanı. ```js selwiseTrack('remove_from_cart', { entityType: 'product', entityId: 'SKU-12345', metadata: { quantity: 1 }, }); ``` ### cart_view Sepet sayfası görüntüleme. **Üretim:** manuel / veri katmanı. ```js selwiseTrack('cart_view', { entityType: 'basket', metadata: { itemCount: 3, total: 1499.7, currency: 'TRY' }, }); ``` ### update_cart Sepet içeriği/adedi güncelleme. **Üretim:** manuel / veri katmanı. ```js selwiseTrack('update_cart', { entityType: 'basket', entityId: 'SKU-12345', metadata: { quantity: 2, currency: 'TRY' }, }); ``` ### cart_abandon ve cart_restore `cart_abandon` **otomatik** üretilir: sepette ürün varken belirli süre (varsayılan 30 dk) işlem yapılmazsa. `cart_restore`, terk edilen sepetin ziyaretçi geri döndüğünde tespit edilmesidir (otomatik / veri katmanı). Bu iki event için genelde kod yazmanız gerekmez; sepet event'lerini (`add_to_cart`, `cart_view`) doğru gönderdiğinizde otomatik çalışır. ### checkout_begin Ödeme sürecinin başlaması. **Üretim:** manuel / veri katmanı. ```js selwiseTrack('checkout_begin', { entityType: 'checkout', metadata: { total: 1499.7, currency: 'TRY', itemCount: 3 }, }); ``` ### checkout_progress Ödeme adımının ilerlemesi (kargo/ödeme bilgisi). **Üretim:** manuel / veri katmanı. ```js selwiseTrack('checkout_progress', { entityType: 'checkout', metadata: { step: 'payment_info' }, // shipping_info | payment_info }); ``` ### checkout_option Ödeme/kargo seçeneğinin seçilmesi (örn. kredi kartı, kapıda ödeme). **Üretim:** manuel / veri katmanı. ```js selwiseTrack('checkout_option', { entityType: 'checkout', metadata: { option: 'credit_card' }, }); ``` ### purchase Satın alma tamamlanması. **Üretim:** `trackOrder` (önerilen) / veri katmanı. Gelir ilişkilendirmesi için `purchase`'ı ham `track` yerine **`trackOrder`** ile gönderin; bu, sunucu tarafı sipariş projeksiyonunu ve son-temas ilişkilendirmesini garanti eder: ```js window.Selwise?.trackOrder({ orderId: 'ORDER-2026-0001', currency: 'TRY', total: 1499.7, items: [{ productItemCode: 'SKU-12345', quantity: 1, unitPrice: 749.9 }], }); ``` Tüm alanlar, tekilleştirme ve platform örnekleri için bkz. [Sipariş Takibi](/docs/integration/order-tracking). ### cart_add_all "Hepsini sepete ekle" düğmesine tek basış (tamamlayıcı kombin önerisi). **Üretim:** otomatik. Sepete giren her satır ayrıca kendi `add_to_cart` olayını üretir; bu olay işlemi sayar, ürünleri değil, ve gelir ilişkilendirmesi **kazandırmaz**. `metadata` alanları: `requested`, `added`, `failed`, `needsSize`, `platform`. ### wishlist Favorilere/istek listesine ekleme. **Üretim:** manuel / veri katmanı. ```js selwiseTrack('wishlist', { entityType: 'product', entityId: 'SKU-12345', metadata: { action: 'add' }, // add | remove }); ``` --- ## Arama olayları (search) Arama modülü etkinse bu olayların çoğu **otomatik** üretilir. Kendi arama arayüzünüzü kullanıyorsanız manuel gönderebilirsiniz. ### search_query Arama sorgusu çalıştırma. **Üretim:** otomatik / veri katmanı / manuel. ```js selwiseTrack('search_query', { entityType: 'search', metadata: { query: 'kablosuz kulaklık', resultsCount: 42 }, }); ``` Veri katmanı karşılığı: ```js window.selwiseLayer.push({ event: 'search_query', search: { query: 'kablosuz kulaklık', results: 42, type: 'faceted' }, }); ``` ### search_results Sonuçların dönmesi (sonuç sayısıyla). **Üretim:** otomatik. Manuel kullanımda: ```js selwiseTrack('search_results', { entityType: 'search', metadata: { query: 'kablosuz kulaklık', resultsCount: 42 }, }); ``` ### search_zero_results Sonuçsuz arama — arama kalitesini iyileştirmek için izlenir. **Üretim:** otomatik / manuel. ```js selwiseTrack('search_zero_results', { entityType: 'search', metadata: { query: 'olmayan ürün' }, }); ``` ### search_filter ve search_sort Filtre (facet) uygulama ve sıralama değiştirme. **Üretim:** otomatik / veri katmanı. ```js selwiseTrack('search_filter', { entityType: 'search', metadata: { query: 'kulaklık', facet: 'renk', values: ['siyah'] }, }); selwiseTrack('search_sort', { entityType: 'search', metadata: { query: 'kulaklık', sortBy: 'price', sortOrder: 'asc' }, }); ``` ### search_page, search_instant_open, search_close `search_page`: sonuç sayfası değişimi. `search_instant_open`: anlık arama kutusunun açılması. `search_close`: arama arayüzünün kapanması. Üçü de arama modülünce **otomatik** gönderilir; özel arayüzde gerekirse aynı `entityType: 'search'` deseniyle manuel gönderebilirsiniz. ### Keşif tıklamaları `product_click` (sonuçtan ürüne tıklama), `category_filter`, `recent_search_click`, `popular_search_click`, `popular_category_click`, `popular_product_click` — hepsi arama/keşif modülünce **otomatik** üretilir. Manuel kullanımda ortak desen: ```js selwiseTrack('popular_product_click', { entityType: 'product', entityId: 'SKU-12345', metadata: { source: 'popular_products' }, }); ``` --- ## Etkileşim olayları (engagement) Kampanya ve widget etkileşimleri. Client script bunları **otomatik** bağlar; normalde kod yazmanız gerekmez. ### impression, click, close Kampanya/widget gösterimi, tıklaması ve kapatılması. Görünürlük IntersectionObserver ile, tıklama ise buton/link etkileşimiyle otomatik yakalanır (buton metni ve hedef URL metadata olarak eklenir). Yalnızca bir yere giden bağlantı, bir düğme ya da kampanya formunun kabul edilen gönderimi `click` üretir; metne, görsele ya da boşluğa tıklama, kapatma düğmesi ve `#` adresli bağlantı üretmez. Özel HTML'de bir öğeyi tıklama saydırmak için `data-selwise-track-click="true"`, bir vazgeçme düğmesini dışarıda tutmak için `data-selwise-ignore-click="true"` ekleyin. Kampanya tıklaması hiçbir zaman ayrıca `add_to_cart` üretmez. Özel bir alanı elle ölçmek isterseniz: ```js selwiseTrack('click', { entityType: 'widget', entityId: 'WIDGET_UUID', metadata: { label: 'Alışverişe Başla', href: '/kampanya' }, }); ``` ### Mesaj bağlantısıyla gelen ziyaret Senaryonun gönderdiği e-posta, SMS ve tarayıcı bildirimlerinde mağazanıza giden bağlantılar `sw_sc` sorgu parametresini taşır; değeri senaryonun kimliğidir (UUID). Bu parametreyle açılan bir sayfada client script **otomatik** olarak bir `click` üretir: `entityType` değeri `messaging`, `entityId` değeri senaryonun kimliği, `metadata.source` değeri `message_link`; bağlantıda `utm_medium` varsa o da `metadata.medium` olarak eklenir. Geçersiz bir değer hiçbir olay üretmez ve aynı sekmede aynı adresin yeniden yüklenmesi ikinci bir tıklama sayılmaz. Bu tıklama, senaryonun mesajlarının sipariş sahiplenmesini sağlar: [Sipariş Atfı Kuralı](/docs/analytics/order-credit#mesajda-neyin-tıklama-sayıldığı). Parametre UTM etiketlemesi kapalı olsa da eklenir, yalnızca kanalın kendi mağazasına giden bağlantılara eklenir ve alıcı hakkında bilgi taşımaz. Sitenizde yönlendirme yapan bir sayfa varsa (örneğin dil ya da bölge seçimi) sorgu dizesini korumasına dikkat edin; `sw_sc` yönlendirmede düşerse tıklama kaydedilmez. ### widget_view, view, hover, scroll `widget_view` (widget görünür oldu), `view` (genel görünürlük), `hover` (üzerine gelme), `scroll` (kaydırma) — hepsi otomatik etkileşim sinyalleridir. Elle göndermeniz gerekmez. ### tab_return ve goal_reached `tab_return`: sekme mesajının (Tab Talk) taşındığı bir sekmeye ziyaretçi geri döndü. `goal_reached`: ekrandaki hedef çubuğunun eşiği aşıldı (ör. ücretsiz kargo). İkisi de **otomatik** üretilir ve bilerek `click` değildir: ziyaretçi zaten dönecek ya da zaten ekleyecek olabilir, bu yüzden **gelir ilişkilendirmesi kazandırmazlar**; yalnızca ölçülür. ### custom_event Tanımladığınız her türlü özel olay. **Üretim:** manuel. ```js selwiseTrack('newsletter_subscribe', { entityType: 'custom', metadata: { source: 'footer' }, }); ``` > **Kendi adınız kanonik değildir** > > `newsletter_subscribe` gibi kanonik listede olmayan bir ad sunucuda `custom_event` olarak saklanır ve olay `Degraded` (Eksik veriyle) işaretlenir; uyarı kodu `UNSUPPORTED_EVENT_NAME_FALLBACK`'tir. Bu bir hata değildir, olay kaybolmaz; ama raporlarda adınızla değil `custom_event` olarak görünür. Ayırt edici bilgiyi `metadata`'ya koyun. Veri katmanı karşılığı: ```js window.selwiseLayer.push({ event: 'custom_event', custom: { name: 'newsletter_subscribe', params: { source: 'footer' } }, }); ``` --- ## Öneri olayları (recommendation) Öneri widget'larıyla etkileşim. Öneri modülü tarafından **otomatik** gönderilir: `widget_impression` (öneri widget'ının gösterimi), `slider_navigate` (ok/nokta ile gezinme), `slider_swipe` (dokunmatik kaydırma). Ayrıca öneri kaynaklı ürün gösterim/tıklama/sepet/satın alma olayları öneri takip endpoint'lerine de bildirilir — bkz. [Public API — Öneriler](/docs/api-reference/public-api). --- ## Kullanıcı olayları (user) Kullanıcı takip modülü varsayılan olarak **kapalıdır**; açık olmasa bile `identify` her zaman çalışır. Kişisel veri göndermekten kaçının (e-postayı hash'leyin). ### identify Anonim ziyaretçiyi bilinen bir kullanıcıyla eşleştirir. `track`'ten farklı olarak ayrı bir metottur: ```js window.Selwise?.identify('USER-8841', { email_hash: '', // ham PII GÖNDERMEYİN plan: 'gold', }); ``` Ayrıntılar: [JavaScript API](/docs/integration/javascript-api). ### user_signup, user_login, user_logout, user_update Kayıt, giriş, çıkış ve profil güncelleme. **Üretim:** manuel / veri katmanı. ```js selwiseTrack('user_signup', { entityType: 'user' }); selwiseTrack('user_login', { entityType: 'user', metadata: { method: 'password' } }); selwiseTrack('user_logout', { entityType: 'user' }); selwiseTrack('user_update', { entityType: 'user', metadata: { field: 'address' } }); ``` Veri katmanı karşılığı: ```js window.selwiseLayer.push({ event: 'user_login', user: { step: 'signin', id: 'USER-8841', loggedIn: true }, }); ``` --- ## Sistem olayları (system) `script_injected` (özel script başarıyla enjekte edildi) ve `script_error` (özel script çalışırken hata oluştu) — özel script çalıştırma telemetrisidir ve **otomatik** üretilir. İzlemeniz için ek kod gerekmez; Özel Scriptler modülünü kullandığınızda çalışır. --- ## Doğrulama Event'lerin doğru aktığını görmek için: 1. **Debug modu** (konsol logları + görsel overlay): ```js localStorage.setItem('selwise_debug', 'true'); location.reload(); ``` 2. **Ağ kontrolü:** DevTools → Network → `events/batch` isteğinin yanıtı `{ accepted: N, rejected: 0 }` olmalıdır. `rejected > 0` ise yanıt gövdesindeki `results[]` hatayı söyler (örn. geçersiz ürün kodu → `degraded`). 3. **Panel kontrolü:** *Tracking Analytics* sayfasında event'ler 1-2 dk içinde görünür. Veri katmanından gelenleri tek tek görmek için **Ayarlar → Entegrasyonlar → Data Layer → View Events** (Settings → Integrations) (son 7 gün; ayrıntı: [Veri Katmanı Ayarları](/docs/integration/data-layer-settings#data-layer-events-ekranı)). Sık karşılaşılan sorunlar: | Belirti | Sebep | | --- | --- | | `events/batch` 403 | `Origin`/`Referer`, doğrulanmış domain ile uyuşmuyor. Bkz. [Domain Doğrulama](/docs/channels/domain-verification). | | Event `degraded` | `productItemCode`, ürün beslemesindeki stok koduyla eşleşmiyor. | | Satın alma var, gelir yok | `trackOrder` çağrılmamış veya `items[].productItemCode` eşleşmiyor. | | Veri katmanı event'leri gelmiyor | Panelde **Enable Data Layer** kapalı (yeni kanalda kapalıdır), ilgili takip modülü kapalı veya değişken adı yanlış. Bkz. [Veri Katmanı Ayarları](/docs/integration/data-layer-settings#neden-boş). | | Hiç event yok | Onay (consent) verilmemiş olabilir; event'ler düşürülür. Bkz. [Onay Yönetimi](/docs/integration/consent). | ## Kanonik event listesi Sunucu, farklı yazımları kanonik adlara normalize eder. Tam liste: ```text page_view, virtual_page_view, category_view, product_view, product_click, product_impression, product_dwell_time, add_to_cart, remove_from_cart, cart_view, update_cart, cart_abandon, cart_restore, checkout_begin, checkout_progress, checkout_option, purchase, wishlist, user_signup, user_login, user_logout, user_update, identify, search_instant_open, search_query, search_filter, search_sort, search_page, search_results, search_zero_results, search_close, category_filter, recent_search_click, popular_search_click, popular_category_click, popular_product_click, impression, click, close, view, hover, scroll, widget_view, widget_impression, slider_navigate, slider_swipe, script_injected, script_error, cart_add_all, tab_return, goal_reached, custom_event ``` Bu liste 52 adın tamamıdır. Kategorileri: `page` (`page_view`, `virtual_page_view`), `commerce` (`product_click` dışındaki ürün olayları, sepet, ödeme ve satın alma olayları, `category_view`, `wishlist`, `cart_add_all`), `search` (arama olayları, keşif tıklamaları ve `product_click`), `engagement` (`impression`, `click`, `close`, `view`, `hover`, `scroll`, `widget_view`, `tab_return`, `goal_reached`, `custom_event`), `recommendation` (`widget_impression`, `slider_navigate`, `slider_swipe`), `user` (`user_*`, `identify`), `system` (`script_injected`, `script_error`). Eski ve alternatif adlar da kabul edilir ve kanonik adlara çevrilir: `checkout_start` → `checkout_begin`, `checkout_complete` ve `order_completed` → `purchase`, `login` → `user_login`, `logout` → `user_logout`, `sign_up` → `user_signup`, `search_opened` → `search_instant_open`, `search_closed` → `search_close`, `zero_results` → `search_zero_results`. Bu olayları kendi sisteminize aktarmak için bkz. [Webhooks](/docs/outbound/webhooks) ve [Webhook Payload ve İmza](/docs/outbound/webhook-payloads). Huni analizleri bu kanonik adlar üzerinden çalışır; çekirdek seti (ürün → sepet → ödeme → satın alma) doğru adlarla göndermek, huni raporlarının anlamlı olmasının ön koşuludur.