Widget Kurulumu

Selwise widget'ı sitenize tek bir <script> etiketiyle, bir etiket yöneticisiyle ya da npm paketiyle kurulur. Bu sayfa script ve etiket yöneticisi yollarını, script'in aldığı öznitelikleri, tek sayfa uygulamalarındaki davranışı ve kurulumu geri alma yollarını anlatır. npm paketi, sürümleme ve önbellek kuralları ve içerik güvenlik politikası (CSP) için npm, Önbellek ve CSP; en kısa yol için Script'i Sitenize Ekleyin.

Ön koşul: kanal, kanal anahtarı ve doğrulama

Kurulumdan önce panelde bir web kanalı tanımlı olmalı. Kanalı ekleme: Kanal Ekleme. Kanalın Channel Key (Kanal Anahtarı) değeri Kanallar → Kanal Özeti (Channels → Channel Overview) ekranındaki kartta durur; tüm kurulum bu anahtarla çalışır.

Kanal doğrulanmamışsa widget içerik çizmez ve olaylar kaydedilmez. Kurulumdan sonra Alan Adı Doğrulama adımını tamamlayın.

CDN ile kurulum

Aşağıdaki satırları sitenizin tüm sayfalarında, <head> içinde, mümkün olduğunca en üstte yerleştirin. Kod <head> dışına konursa izleme çalışır ama değişiklikler sayfa çizildikten sonra uygulanır. SITE_KEY yerine kendi anahtarınızı yazın.

<link rel="preconnect" href="https://widget.selwise.com" crossorigin>
<link rel="preconnect" href="https://api.selwise.com" crossorigin>
<script>window.Selwise=window.Selwise||{};window.Selwise.q=window.Selwise.q||[];['track','trackOrder','identify','setTraits','pushDataLayer','grantConsent','revokeConsent','showConsentPreferences','withdrawConsent','endJourney'].forEach(function(m){if(!window.Selwise[m])window.Selwise[m]=function(){window.Selwise.q.push([m,arguments])}});</script>
<script async src="https://widget.selwise.com/client.js" data-site-key="SITE_KEY"></script>

Script yüklendiğinde data-* özniteliklerini okuyarak otomatik başlatılır; ayrıca Selwise.init() çağırmanıza gerek yoktur ve window.Selwise nesnesi kendiliğinden oluşur.

Üstteki üç satır birlikte çalışır:

Satır	Ne yapar
preconnect (iki satır)	İki hosta DNS ve TLS el sıkışmasını erken başlatır; 100-300 ms kazanç. Atlanabilir, ama bedelsizdir
Komut kuyruğu	async yüklemede window.Selwise henüz yokken yapılan trackOrder, identify gibi çağrıları tamponlar ve widget hazır olunca sırayla oynatır. Bu satır olmadan async sipariş kaybettirir: window.Selwise?.trackOrder(...) çağrısı widget gelmeden çalışırsa ?. hatasız sessizce hiçbir şey yapmaz
async script	HTML ayrıştırmasını durdurmaz. Senkron hâli canlı bir vitrinde 210 ms ölçüldü (yavaş mobil bağlantıda 1-2 sn)

Komut kuyruğunun garantileri: çağrılar widget'ın init() işi (yapılandırma ve onay durumu yüklenmesi) bittikten sonra, çağrıldıkları sırayla oynatılır; bir kez oynatılan çağrı bir daha oynatılmaz; bozuk bir çağrı diğerlerini durdurmaz. Kuyruğa girebilen yöntemler: track, trackOrder, identify, setTraits, pushDataLayer, grantConsent, revokeConsent, showConsentPreferences, withdrawConsent, endJourney. getVisitorId() gibi değer döndüren yöntemler kuyruklanmaz; onları widget yüklendikten sonra çağırın (bkz. Hazır olma).

Script öznitelikleri

Öznitelik	Zorunlu	Açıklama
data-site-key	Evet	Kanalın anahtarı. Yoksa widget başlamaz ve konsola No site key — widget not started hatası yazar
data-api-url	Hayır	API taban adresi. CDN sürümünde etkisizdir: adres derleme sırasında https://api.selwise.com olarak sabitlenir ve bu öznitelik onu geçersiz kılamaz. Özel bir adres gerekiyorsa bkz. npm paketi
data-env	Hayır	development verilirse geliştirici tanılama araçları açılır. Üretimde kullanmayın

data-sentry-dsn, data-sentry-environment ve data-sentry-release Selwise'in kendi hata raporlaması içindir; mağaza kurulumunda kullanılmaz.

Script etiketinin bulunması

Widget kendi etiketini document.currentScript ile bulur. Bu değer bir etiket yöneticisinden enjekte edilen scriptte, bir modül scriptinde ve olay işleyicilerinde null'dır; bu durumda widget data-site-key taşıyan script etiketini kendisi arar (iki tane varsa sonuncuyu alır). Yani etiket yöneticisiyle kurulum çalışır.

Etiket yöneticisi (Google Tag Manager) ile kurulum

GTM'de Custom HTML türünde yeni bir etiket oluşturun. Aşağıdaki kod, komut kuyruğunu kurar ve script'i enjekte eder:

<script>
  (function () {
    window.Selwise = window.Selwise || {};
    window.Selwise.q = window.Selwise.q || [];
    ['track','trackOrder','identify','setTraits','pushDataLayer','grantConsent','revokeConsent','showConsentPreferences','withdrawConsent','endJourney']
      .forEach(function (m) {
        if (!window.Selwise[m]) window.Selwise[m] = function () { window.Selwise.q.push([m, arguments]); };
      });

    if (document.querySelector('script[data-site-key]')) return; // ikinci kez eklenmesin
    var s = document.createElement('script');
    s.async = true;
    s.src = 'https://widget.selwise.com/client.js';
    s.setAttribute('data-site-key', 'SITE_KEY');
    document.head.appendChild(s);
  })();
</script>

• Tetikleyici: Initialization - All Pages (ya da All Pages - Page View). Tek bir tetikleyici yeter; etiketin sayfa başına bir kez çalıştığından emin olun (Tag firing options ayarında sayfa başına bir kez).
• Çerez izni. Selwise kendi onay denetimini yönetir (Onay Yönetimi); etiketi GTM'in onay modu arkasına koyarsanız widget, onay verilene kadar hiç yüklenmez ve onay öncesi olayları bekletemez. Kendi onay çözümünüz varsa grantConsent() / revokeConsent() ile kararı bildirin.
• Gizleme garanti edilmez. GTM etiketleri çoğunlukla sayfanın ilk çiziminden sonra çalışır; bu yüzden A/B test ve kişiselleştirme değişiklikleri kısa süre orijinal sayfa görünerek uygulanabilir. İlk çizimden önce gizleme için panelin verdiği kodu ayrıca doğrudan sitenizin <head> içine ekleyin. Kanal sayfası bu kurulumu GTM ile kurulu olarak gösterir.
• Verify Now, GTM ile kurulan etiketi tanır: ham HTML'de bulamazsa sayfanın GTM kapsayıcılarının yayımlanmış sürümüne bakar (kapsayıcıyı yayımlayın).
• GTM'in kendi dataLayer'ı (window.dataLayer) olduğu gibi okunur: bkz. Veri Katmanı.
• GTM etiketi geç yüklenir; bu yüzden trackOrder gibi çağrıların komut kuyruğundan geçmesi şarttır.

npm paketi

Script etiketi yerine bir paket yöneticisiyle kurulum; dağıtılan dosyaların önbelleği, CSP ve service worker ayrı sayfada: npm, Önbellek ve CSP.

Başlatma akışı

Script yüklendiğinde widget şu istekleri bu sırayla ve çoğunu paralel yapar; hepsi https://api.selwise.com/api/v1 altındadır:

1. GET /public/sites/:siteKey/config?p=4: kampanya, öneri, takip, arama, zenginleştirme, deney ve tema yapılandırmasının toplu yanıtı (Public API). Başarısız olursa widget tracking-config, campaigns ve recommendations uçlarına tek tek düşer.
2. GET /public/sites/:siteKey/scripts?path=<sayfa yolu>: o sayfaya tanımlı özel script'ler.
3. GET /public/sites/:siteKey/integrations: veri katmanı ve entegrasyon ayarları.
4. Yapılandırma geldikten sonra: deney ataması (GET /public/experiments/assign) ve segment değerlendirmesi (POST /public/segments/evaluate), yalnızca bunları kullanan kampanya ya da deney varsa.
5. Olaylar (POST .../events/batch), bir sayfa görüntülemeyle başlar. Yalnızca etkin özelliğin parçası indirilir.
6. Ürün sayfasında zenginleştirme kuralı varsa GET .../enrichments?code=...; kampanya metni ürün yer tutucusu kullanıyorsa GET .../product-facts?code=...; kanalda site içi teslimat yapan senaryo varsa GET .../scenarios/inbox.

Hepsinin istek ve yanıt ayrıntısı: Public API.

Tek sayfa uygulamaları ve sayfa geçişleri

Widget, sayfa yenilemeden gezinen mağazalarda (Next.js, PZ Next, Turbo, React Router, Vue Router) URL değişimini kendisi algılar: history.pushState ve history.replaceState'i sarmalar ve popstate olayını dinler. URL (hash dahil) değiştiğinde:

1. Önceki sayfanın çizdiği kampanya kökleri, arama ve öneri modülleri, zenginleştirme blokları, sayfa üstü deney, Tab Talk ve özel script'ler temizlenir.
2. Veri katmanı yeniden kurulur; olay kuyrukları atılmaz (sayfadan ayrılırken sıradaki olaylar kaybolmaz).
3. 100 ms sonra yeni sayfa için arama, öneri, zenginleştirme ve kampanya değerlendirmesi yeniden yapılır; sayfa görüntüleme sayılır.

Yani Selwise.init()'i yeniden çağırmayın, script'i yeniden eklemeyin. Kendi router'ınız history API'sini kullanmıyorsa (yalnızca hashchange ya da özel bir mekanizma) geçiş algılanmaz; bu durumda history.pushState ile URL'i güncelleyin.

Turbo (Hotwire) gibi sayfa değiştirme kütüphaneleri her gezintide <head>'i ya da <body>'yi yeniden yazıyorsa script etiketinin yeniden çalışmadığından emin olun: widget bir sayfada iki örnek başlatılmasına karşı korunmaz, ikinci bir örnek çift olay ve çift çizim demektir. Etiket yöneticisiyle kuruyorsanız etiketin ateşleme seçeneğini sayfa başına bir kez olacak şekilde tutun.

Kurulumu doğrulayın

1. Alan adı doğrulaması yapın. Doğrulanmamış kanalda widget içerik çizmez.
2. Tarayıcı konsolunda debug modunu açın:

localStorage.setItem('selwise_debug', 'true');
location.reload();

3. DevTools Network sekmesinde şunları görün: config?p=4 (200), scripts?path=..., integrations, sonra events/batch (200, yanıtta "success": true). Başarılı bir config yanıtı tek başına widget'ın yüklendiğini ve kanalın doğrulandığını kanıtlar.
4. Konsolda window.Selwise bir nesne olmalı (window.Selwise.getVisitorId() bir kimlik döndürmeli).

Bir şey yolunda gitmezse adım adım teşhis için Takip Sorunları ve Widget Görünmüyor sayfalarına bakın.

Kurulumu geri alma ve devre dışı bırakma

Amaç	Yol
Widget'ı tamamen kaldırmak	<script> etiketini (ve komut kuyruğu satırını) şablonlarınızdan silin. Ziyaretçi tarafında selwise_ önekli depolama anahtarları kalır ve zararsızdır
Çalışan bir sayfada geçici durdurmak	window.Selwise.destroy(): dinleyicileri, çizilmiş içeriği, modülleri ve history sarmalayıcısını geri alır; örnek window.Selwise'tan silinir
Kampanyaları yayından almak	Panelde kampanyayı Paused yapın ya da tarih penceresini kapatın; widget script'i olduğu gibi kalır
Çerez onayı gelene kadar beklemek	Cookie Consent → Policy sekmesinde Require consent before tracking ve Hold events until the answer ayarlarını açın; script yüklü kalır, olaylar onay gelene kadar gönderilmez
Domain'i değiştirmek	Kanal alan adını değiştirmek doğrulamayı sıfırlar; yeni alan adı doğrulanana kadar widget orada çalışmaz

Ziyaretçide kalan depolama anahtarları: selwise_vid, selwise_sid, selwise_suid, selwise_journey_*, selwise_experiments, selwise_frequency_caps, selwise_consent_<siteKey>, selwise_test_mode, selwise_debug (tam liste: JavaScript API). Bir kullanıcının silme talebinde bunları sizin temizlemeniz gerekmez; sunucu tarafı silme için KVKK ve GDPR Talepleri.