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ım | Kim yapar | Nerede |
|---|---|---|
| 1–6 | Anket yöneticisi | SARP CX paneli |
| 7–9 | Sitenin geliştiricisi | Müşteri web sitesi |
| 10 | Sitenin geliştiricisi (sunucu tarafı) | Müşteri web sitesinin backend’i |
| 11 | İkisi birlikte | Canlı 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.
8.1 Adım 1: Anketi hazırlayın
Bölüm başlığı “8.1 Adım 1: Anketi hazırlayın”- 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.
- Ayarlar → Gizli Anahtarlar ekranında yeni bir secret oluşturun (uzun, rastgele bir değer).
- Aynı değeri, güvenli bir kanaldan sitenin geliştiricisine iletin. Değer yalnızca sitenin sunucusunda durmalıdır.
- Secret’ın adını not edin; Adım 3’te kanala bu adı yazacaksınız.
8.3 Adım 3: Kanalı oluşturun
Bölüm başlığı “8.3 Adım 3: Kanalı oluşturun”Anketler → anket → Dağıtım → Web Widget → Yeni kanal. Editörün Genel sekmesi:
| Alan | Ne yazılır |
|---|---|
| Kanal adı | Panelde görünecek ad (ör. “Kurumsal site · footer”). Ziyaretçiye gösterilmez. |
| İzin verilen adresler | Zorunlu. 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 aktif | Açı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’ler | Boş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):
| Desen | Eşleşir |
|---|---|
/odeme | Yolu /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 |
8.4 Adım 4: Görünümü ayarlayın
Bölüm başlığı “8.4 Adım 4: Görünümü ayarlayın”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.
8.5 Adım 5: Davranışı ayarlayın
Bölüm başlığı “8.5 Adım 5: Davranışı ayarlayın”Davranış sekmesi:
| Alan | Açıklama |
|---|---|
| Başlatıcı biçimi | Kenar 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çimi | Modal (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öster | Kapalı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ın | Kapatma düğmesi her durumda görünür. |
| Mobil cihazlarda göster | Telefonda 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:
| Ayar | Uygulandığı yer | Not |
|---|---|---|
| Gösterim oranı (%) | Tarayıcı | Trafiği seyreltmek içindir, kesin bir kota değildir. |
| Ziyaretçiye bir kez göster | Tarayı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) | Sunucu | Yanıt veren kişiye bu süre boyunca anket tekrar gösterilmez. Kesindir. |
| Kota (yanıt) | Sunucu | Bu 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.
8.6 Adım 6: Panelden test edin
Bölüm başlığı “8.6 Adım 6: Panelden test edin”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.
8.7 Adım 7: Kodu siteye yerleştirin
Bölüm başlığı “8.7 Adım 7: Kodu siteye yerleştirin”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.jsyüklenmeden önce yapılanTKSurvey(...)ç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-srcveframe-srclistelerine eklenmelidir; aksi halde yükleyici ya da anket penceresi tarayıcı tarafından engellenir.
Komutlar:
| Komut | Ne 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' });8.9 Adım 9: Kendi düğmenizden açın (opsiyonel)
Bölüm başlığı “8.9 Adım 9: Kendi düğmenizden açın (opsiyonel)”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;
openile 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.
Tarayıcı tarafı
Bölüm başlığı “Tarayıcı tarafı”TKSurvey('identify', { customer: { signature: '<sunucunun ürettiği HMAC>' }, attributes: { // opsiyonel; gizli soruların dış anahtarları CUST_FRST_NM: 'Ayşe', CBN_CLS: 'BUSINESS' }});customeryanı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.attributesdeğ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.
Sunucu tarafı: imzanın üretilmesi
Bölüm başlığı “Sunucu tarafı: imzanın üretilmesi”İ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 JSONHem 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.
8.11 Adım 11: Canlıda doğrulayın
Bölüm başlığı “8.11 Adım 11: Canlıda doğrulayın”- 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.
- Anketi doldurup gönderin. Pencere kendiliğinden kapanır.
- 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.
- 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.
8.12 Sorun giderme
Bölüm başlığı “8.12 Sorun giderme”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:
HTTP | Anlamı | Ne yapılır |
|---|---|---|
404 | Kanal anahtarı tanınmıyor | Kodu Kodu al penceresinden yeniden kopyalayın. |
403 | Origin izinli değil, ya da oturum jetonu yok/geçersiz | Sitenin adresini İzin verilen adresler listesine ekleyin (https://, yolsuz, sonda / yok). |
423 | Kanal duraklatılmış, kota dolmuş, tarih aralığı dışında, public erişim kapalı ya da anket taslak | Kanalın aktif olduğunu, Başlangıç/Bitiş aralığını, kotayı ve anketin yayında ve public erişiminin açık olduğunu kontrol edin. |
410 | Anket 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-srcveframe-srciçinde izin veriyor mu?