İçeriğe geç

8. Web widget

Siteye yapıştırılan kısa bir kod parçasıyla anket, sayfanın kenarında bir sekme ya da yuvarlak düğme olarak görünür; ziyaretçi tıklayınca anket sayfanın üzerinde bir pencerede açılır. Kod parçası sabittir ve sürüm 1’de dondurulmuştur; davranış değişiklikleri yüklenen dosyadan gelir, sayfaya bir daha dokunulması gerekmez.

  • YönZiyaretçi tarayıcısı → SARP CX
  • KimlikOrigin allowlist (zorunlu)
  • Kanal anahtarıtk_ch_… · gizli değil
  • Limit600 açılış / dk · kanal+IP

Her gömme noktası bir kanaldır: kendi anahtarı, izinli siteleri, görünümü, davranışı ve sayaçları vardır. Bir anketin birden fazla kanalı olabilir (örneğin aynı anket hem kurumsal sitede hem kampanya sayfasında).

Entegrasyon iki tarafın işidir:

AdımKim yaparNerede
1–6Anket yöneticisiSARP CX paneli
7–9Sitenin geliştiricisiMüşteri web sitesi
10Sitenin geliştiricisi (sunucu tarafı)Müşteri web sitesinin backend’i
11İkisi birlikteCanlı site + panel

Adım 2 ve 10 yalnızca yanıtları müşteriye bağlamak ya da CRM bilgisi taşımak istiyorsanız gereklidir; anonim bir widget için atlanabilir.

  • Anket yayında olmalıdır. Taslak ya da kapatılmış anket widget’ta görünmez.
  • Anketin public erişimi açık olmalıdır (Dağıtım → Public Link, sağ üstteki anahtar). Public erişim kapalıysa anket kanallarda da kapanır.
  • CRM bilgisi taşıyacaksanız (Adım 10), ankete bu bilgileri karşılayacak gizli sorular ekleyin ve her birine bir dış anahtar (external key) verin: örneğin CUST_FRST_NM, CBN_CLS. Sitenin göndereceği anahtar adları bunlarla birebir aynı olmalıdır.

8.2 Adım 2: İmza anahtarını tanımlayın (opsiyonel)

Bölüm başlığı “8.2 Adım 2: İmza anahtarını tanımlayın (opsiyonel)”

Yanıtın kime ait olduğunu bilmek ya da CRM bilgisi taşımak istiyorsanız bir imza anahtarı gerekir; çünkü bu bilgileri taşıyan ziyaretçinin kendi tarayıcısıdır ve imzasız bir sayfada herkes kendini başkası ilan edebilirdi.

  1. Ayarlar → Gizli Anahtarlar ekranında yeni bir secret oluşturun (uzun, rastgele bir değer).
  2. Aynı değeri, güvenli bir kanaldan sitenin geliştiricisine iletin. Değer yalnızca sitenin sunucusunda durmalıdır.
  3. Secret’ın adını not edin; Adım 3’te kanala bu adı yazacaksınız.

Anketler → anket → Dağıtım → Web Widget → Yeni kanal. Editörün Genel sekmesi:

AlanNe yazılır
Kanal adıPanelde görünecek ad (ör. “Kurumsal site · footer”). Ziyaretçiye gösterilmez.
İzin verilen adreslerZorunlu. Her satıra bir adres: https://www.ornek.com. Alt alan adları için https://*.ornek.com. Yol ve sondaki / yazılmaz. Widget yalnızca bu sitelerde açılır.
Kanal aktifAçık bırakın. Kapattığınızda widget siteden anında kaybolur; koda dokunmak gerekmez.
Varsayılan dil“Anketin dili”, Türkçe ya da İngilizce. Aynı anketi farklı dildeki sayfalara gömerken kanalın dilini sabitler.
Etkin URL’lerBoşsa izinli sitenin tüm sayfalarında görünür. Doldurursanız yalnızca eşleşen sayfalarda açılır (aşağıya bakın).
Başlangıç / BitişKanalın yayın penceresi. Boşsa süresizdir. Pencere dışında widget görünmez; kodun sitede kalması sorun değildir.
Güvenli mod · imza anahtarıAdım 2’deki secret’ın adı (değeri değil). Boşsa kimlik ve CRM bilgileri hiç kabul edilmez.

İzinli origin listesi birebir eşleşme ya da https://*.alanadi alt alan adı jokeri kabul eder. Eşleşmeyen ya da Origin başlığı taşımayan istek 403 alır; CORS yanıtı eşleşen origin’i döner, hiçbir zaman * vermez.

Etkin URL’ler desen biçimi (regex değildir):

DesenEşleşir
/odemeYolu /odeme ile başlayan sayfalar (/odeme/adim-2 dahil)
/urun/*/yorum* tek bir yol parçası yerine geçer
*kampanya*Adresin herhangi bir yerinde kampanya geçen sayfalar
https://www.ornek.com/xŞema ile yazılırsa tam adres karşılaştırılır

Görünüm sekmesi:

  • Ana renkbaşlatıcı düğmesi ve form vurguları.
  • Buton yazı rengi“Devam Et” ve “Gönder” yazısı. Boşsa ana renge göre siyah ya da beyaz seçilir.
  • Metin rengibaşlık, soru ve seçenek metinleri. Beyaz zemin üzerinde okunamayacak kadar açık bir renk uygulanmaz.
  • Logo adresiformun üstündeki logo.

Davranış sekmesi:

AlanAçıklama
Başlatıcı biçimiKenar sekmesi, Yuvarlak düğme ya da Gösterme (sadece kod ile açılır): kendi düğmenizi kullanacaksanız bunu seçin (Adım 9). Konum (sağ/sol), düğme yazısı, ikon boyutu, üst konum ve kenar boşluğu (20px, 50% gibi CSS değerleri).
Açılış biçimiModal (sayfayı karartır, ortada) ya da Köşe balonu (sayfa okunmaya devam eder). Genişlik ve köşe yuvarlaklığı (px). Telefonda ikisi de aynı görünür.
Sayfa açılır açılmaz gösterKapalıyken form, ziyaretçi başlatıcıya tıklayana kadar açılmaz.
Çıkışta gösterİmleç sayfanın üstünden çıkarken (sekmeyi kapatmaya giderken) formu bir kez açar. Dokunmatik cihazlarda çalışmaz.
Dışarı tıklayınca kapansınKapatma düğmesi her durumda görünür.
Mobil cihazlarda gösterTelefonda gösterilip gösterilmeyeceği.

Sıklık ve kota ayarlarının bir kısmı tarayıcıda, bir kısmı sunucuda uygulanır:

AyarUygulandığı yerNot
Gösterim oranı (%)TarayıcıTrafiği seyreltmek içindir, kesin bir kota değildir.
Ziyaretçiye bir kez gösterTarayıcıTarayıcı hafızasına yazılır; hafıza temizlenirse yeniden görünür.
Gösterim aralığı (gün)Tarayıcı“Bir kez göster”in yumuşak hâli.
Yanıt sonrası sessiz kalma (gün)SunucuYanıt veren kişiye bu süre boyunca anket tekrar gösterilmez. Kesindir.
Kota (yanıt)SunucuBu sayıda yanıt toplanınca kanal kendiliğinden kapanır.

Kaydet’e basın. Görünüm ve davranış ayarları anket yayındayken de değiştirilebilir; değişiklik sitedeki kodu güncellemeden yansır.

Kanal satırındaki Test et, widget’ı yeni bir sekmede gerçek yükleyiciyle açar. İzinli adres listesine bir şey eklemek gerekmez ve sayaçlar (gösterim, açılış) etkilenmez. Görünümü ve davranışı burada son haline getirin.

Kanal satırındaki Kodu al penceresinden kodu kopyalayın ve sitenin geliştiricisine iletin. Kod, sitenin her sayfasında </body> etiketinden hemen önce bir kez yer almalıdır (genellikle ortak footer şablonu):

<script>
!function(w,d,s,o){w.TKSurveyObject=o;w[o]=w[o]||function(){(w[o].q=w[o].q||[]).push(arguments)};
var js=d.createElement(s);js.src='https://<anket-alan-adı>/survey-widget.js';js.async=1;
var f=d.getElementsByTagName(s)[0];f.parentNode.insertBefore(js,f)}(window,document,'script','TKSurvey');
TKSurvey('boot', 'tk_ch_XXXXXXXXXXXXXXXXXXXXXXXX');
</script>
  • Kodu Kodu al penceresinden olduğu gibi kopyalayın; anket alan adı ve kanal anahtarı pencerede doğru değerlerle gelir.
  • Kod bir komut kuyruğudur: survey-widget.js yüklenmeden önce yapılan TKSurvey(...) çağrıları kaybolmaz, dosya yüklenince sırayla işlenir. Bu yüzden sonraki adımlardaki çağrılar kodun hemen altına ya da sayfanın herhangi bir yerine yazılabilir.
  • Sitenin bir Content-Security-Policy başlığı varsa anket alan adı script-src ve frame-src listelerine eklenmelidir; aksi halde yükleyici ya da anket penceresi tarayıcı tarafından engellenir.

Komutlar:

KomutNe yapar
TKSurvey('boot', anahtar, { lang })Widget’ı başlatır.
TKSurvey('identify', { customer, attributes })Ziyaretçi kimliğini ve CRM bilgilerini iletir (Adım 10).
TKSurvey('open')Anketi açar.
TKSurvey('close')Anketi kapatır.

Tanınmayan bir komut hata vermez, sessizce yok sayılır.

8.8 Adım 8: Ziyaretçinin dilini bildirin (opsiyonel)

Bölüm başlığı “8.8 Adım 8: Ziyaretçinin dilini bildirin (opsiyonel)”

Sayfa birden fazla dilde yayınlanıyorsa, sayfanın dilini boot çağrısına üçüncü parametre olarak verin. Bu değer kanalın ve anketin varsayılan dilini ezer:

TKSurvey('boot', 'tk_ch_…', { lang: 'en' });

Örneğin <html lang="…"> değerini kullanmak için:

TKSurvey('boot', 'tk_ch_…', { lang: document.documentElement.lang || 'tr' });

Hazır sekme ya da düğme yerine sitenin kendi bağlantısından açmak için, Adım 5’te Başlatıcı biçimi’ni Gösterme yapın ve şu çağrıyı kullanın:

<button type="button" id="anket-ac">Görüşünüzü paylaşın</button>
<script>
document.getElementById('anket-ac').addEventListener('click', function () {
TKSurvey('open');
});
</script>

TKSurvey('close') anketi koddan kapatır.

  • Etkin URL’ler dışında kalan bir sayfada ya da Mobil cihazlarda göster kapalıyken telefonda open çağrısı bir şey yapmaz.
  • Gösterim oranı ve bir kez göster yalnızca hazır başlatıcıyı etkiler; open ile bilinçli açılan anket bunlara takılmaz.

8.10 Adım 10: Ziyaretçi kimliği ve CRM bilgileri (opsiyonel)

Bölüm başlığı “8.10 Adım 10: Ziyaretçi kimliği ve CRM bilgileri (opsiyonel)”

Site, giriş yapmış ziyaretçinin kim olduğunu ve CRM’deki bazı değerlerini ankete bildirebilir. Bu adım için kanalda Güvenli mod (imza anahtarı) tanımlı olmalıdır (Adım 2–3); tanımlı değilse kimlik ve CRM bilgileri yok sayılır ve yanıt anonim kaydedilir.

TKSurvey('identify', {
customer: {
externalId: 'MUSTERI-123', // ya da email: '[email protected]'
signature: '<sunucunun ürettiği HMAC>'
},
attributes: { // opsiyonel; gizli soruların dış anahtarları
CUST_FRST_NM: 'Ayşe',
CBN_CLS: 'BUSINESS'
}
});
  • customer yanıtı bu müşteriye bağlar. Kimlik hiçbir zaman URL’de taşınmaz; kendisi saklanmaz, yalnızca geri döndürülemez bir özeti tutulur. Hiçbir soruyu önceden doldurmaz. Aynı kişinin tekrar yanıtlamasını engelleyen Yanıt sonrası sessiz kalma kuralı da bu özete göre çalışır.
  • attributes değerleri, ankette aynı dış anahtara sahip gizli sorulara sunucuda yazılır; mantık kuralları bu değerlere göre dallanabilir. Eşleşmeyen anahtarlar sessizce yok sayılır. Değerler metin olmalıdır.
  • identify, boot’tan önce ya da sonra çağrılabilir; ancak ziyaretçi anketi açmadan önce çağrılmış olmalıdır.

İmza sitenin sunucusunda üretilir ve sayfaya yazılır; secret tarayıcıya asla inmemelidir.

imza = HMAC_SHA256(secret, mesaj) → hex
mesaj = externalId (yoksa email)
+ attributes gönderiliyorsa: "\n" + kanonik JSON

Hem externalId hem email gönderiliyorsa mesajın kimlik kısmı externalId’dir.

Kanonik JSON kuralları (başka bir dilde de birebir uyulmalıdır):

  • Anahtarlar bayt sırasına göre sıralanır (sayı gibi görünen anahtarlar da metin olarak).
  • Boşluk yoktur.
  • Türkçe karakterler kaçış yapılmadan, UTF-8 olarak kalır.
  • / karakteri kaçırılmaz.

Node.js

import { createHmac } from 'node:crypto';
function surveySignature(secret, identity, attributes) {
const keys = Object.keys(attributes ?? {}).sort();
let message = identity;
if (keys.length > 0) {
const body = keys
.map((k) => JSON.stringify(k) + ':' + JSON.stringify(attributes[k]))
.join(',');
message += '\n{' + body + '}';
}
return createHmac('sha256', secret).update(message, 'utf8').digest('hex');
}
// surveySignature(process.env.SURVEY_SECRET, 'MUSTERI-123', { CUST_FRST_NM: 'Ayşe', CBN_CLS: 'BUSINESS' })

PHP

function survey_signature(string $secret, string $identity, array $attributes = []): string {
$message = $identity;
if (count($attributes) > 0) {
ksort($attributes, SORT_STRING);
$message .= "\n" . json_encode($attributes, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
}
return hash_hmac('sha256', $message, $secret);
}

Kanal listesinde İmza anahtarı bulunamadı uyarısı görünüyorsa kanala yazılan secret adı okunamıyor demektir; bu durumda da tüm yanıtlar anonim kaydedilir.

  1. Sitenin izinli bir sayfasını gizli pencerede açın (tarayıcıdaki “bir kez göster” kaydı temiz olsun). Başlatıcı görünmeli.
  2. Anketi doldurup gönderin. Pencere kendiliğinden kapanır.
  3. Panelde kanal satırındaki Yanıt sayacının arttığını görün. Gösterim ve Açılma sayaçları yaklaşık bir dakika gecikmeyle yansır; yanıt sayısı anlık ve kesindir.
  4. Yanıtı Anket Geri Bildirimleri ekranında açın. Adım 10’u yaptıysanız yanıtın müşteriye bağlandığını ve gizli soruların CRM değerleriyle dolduğunu kontrol edin.

Widget bir hata durumunda sitede hiçbir şey göstermez ve konsola hata yazmaz; bu, yetkisiz bir sitenin hangi anahtarların var olduğunu öğrenmesini engellemek içindir. Görünmüyorsa tarayıcının geliştirici araçlarında Network sekmesinde channels/tk_ch_… isteğinin yanıt koduna bakın:

HTTPAnlamıNe yapılır
404Kanal anahtarı tanınmıyorKodu Kodu al penceresinden yeniden kopyalayın.
403Origin izinli değil, ya da oturum jetonu yok/geçersizSitenin adresini İzin verilen adresler listesine ekleyin (https://, yolsuz, sonda / yok).
423Kanal duraklatılmış, kota dolmuş, tarih aralığı dışında, public erişim kapalı ya da anket taslakKanalın aktif olduğunu, Başlangıç/Bitiş aralığını, kotayı ve anketin yayında ve public erişiminin açık olduğunu kontrol edin.
410Anket kapatılmışAnketi yeniden yayınlayın ya da kanalı başka bir ankete taşıyın.

İstek başarılı (200) olduğu halde widget görünmüyorsa:

  • Sayfa Etkin URL’ler desenlerinden biriyle eşleşiyor mu?
  • Gösterim oranı, bir kez göster ya da gösterim aralığı nedeniyle mi gizlendi? Gizli pencerede deneyin.
  • Telefondan deneniyorsa Mobil cihazlarda göster açık mı?
  • Başlatıcı biçimi Gösterme ise widget yalnızca TKSurvey('open') ile açılır.
  • Telefonda, ekran 640 pikselden darsa ve Mobil cihazlarda göster kapalıysa widget hiç yüklenmez.
  • Sitenin CSP başlığı anket alan adını script-src ve frame-src içinde izin veriyor mu?