Site Widget'ı

Widget, botunuzun sohbetinin doğrudan sitenizde olması demektir: sayfanın köşesinde bir yuvarlak düğme ve ondan açılan bir yazışma. Ziyaretçi için size ulaşmanın bir yolu daha; bot için ise sıradan bir kanal — mesajlaşma uygulamalarındakiyle aynı tepkiler ve aynı operatör diyalogları. Çok kanallılığa genel bakış: Kanallar.

Kurulum, site şablonuna tek bir kod parçası yapıştırmaktan ibarettir. Geri kalan her şey panelde ayarlanır ve siteye tekrar dokunmadan uygulanır.

Yerleştirme kodunu nereden alırsınız

Panelde Widget → Siteye kurulum bloğu → Yerleştirme kodu alanını açın. Kopyala düğmesi tüm parçayı panoya alır.

Kod şöyle görünür — üç noktanın yerinde sizin kendi anahtarınızla:

<script>
  window.mybot = { key: "eu-1a2b3c4d-..." };
</script>
<script async src="https://getmybot.dev/loader.js"></script>

Kod yerine "bu bot için henüz kurulum anahtarı verilmedi" yazısını görüyorsanız, site widget kanalı bota bağlanmamış demektir. Destek ekibine yazın: anahtar, kanal bağlandığında verilir.

Kodun altında widget'ın hangi adrese bağlanacağını gösteren bir ipucu vardır. Sitenizde CSP (Content Security Policy) varsa bu adrese betik yükleme ve ağ isteği izni verin; aksi halde tarayıcı widget'ı sessizce engeller.

Kod nereye eklenir

Parça, widget'ın görünmesi gereken her sayfanın HTML'ine eklenir. Pratikte bu, sitenin ortak şablonuna bir kez eklemek demektir: alt bilgi, CMS'teki "</body> öncesi kod" alanı ya da etiket yöneticisindeki bir konteyner.

Kurallar kısa:

  • En iyi yer kapanış </body> etiketinden hemen önce. <head> de çalışır ama o zaman tarayıcı içeriğinizden önce widget'a zaman ayırır.
  • İki etiketin sırası önemlidir: ilki anahtarı belirler, ikincisi widget'ı yükler. Yerlerini değiştirmeyin ve sayfaya dağıtmayın.
  • İkinci etikette async vardır ve çizimi engellemez. Bu özniteliği kaldırmayın.
  • Sayfa başına bir parça. İki kopya, iki başlatma denemesi demektir.

Gerisini yükleyici halleder: botunuzun hangi veri merkezinden hizmet aldığını belirler ve widget kodunu oradan çeker. Bunun için sizden bir şey gerekmez.

Kurulum anahtarı herkese açıktır

İlk etiketteki anahtar, botunuzun herkese açık kimliğidir, parola değil. Sayfa kaynağında durur: her ziyaretçi "Sayfa kaynağını görüntüle" ile onu okuyabilir. Her sohbet widget'ı böyle çalışır ve bu normaldir.

Önemli olan:

  • Anahtarla panele girilemez, başkalarının diyalogları okunamaz, abone tabanı dışa aktarılamaz ve botta hiçbir şey değiştirilemez. Tam olarak tek bir şeyi mümkün kılar: bu botla yeni bir yazışma başlatmak.
  • Anahtarı sır gibi görmeyin: gizlemek ya da karartmak bir şey kazandırmaz.
  • Anahtarın değiştirilmesi gerekiyorsa (örneğin bir yükleniciyle yollarınızı ayırdıysanız) bunu destek yapar. Değişimden sonra sitedeki eski kod çalışmaz ve güncellenmesi gerekir.

İzin verilen alan adları listesi

Widget'ın bir izin verilen alan adları listesi (origin allowlist) vardır: widget'ın çalışmasına izin verilen site adresleri. Liste kanal bağlanırken belirlenir ve sonradan anahtar yeniden üretilmeden değiştirilir; sitedeki kodunuz aynı kalır.

Girdiler origin'dir: şema, ana makine ve standart değilse port.

https://example.com
https://www.example.com
https://shop.example.com
http://localhost:3000

Karşılaştırma birebir, karakter karakterdir:

  • Joker karakter yoktur. https://*.example.com çalışmaz — alt alan adlarını tek tek yazın.
  • example.com ve www.example.com farklı girdilerdir. Site her ikisinde de açılıyorsa ikisini de ekleyin.
  • http:// ve https:// de farklı girdilerdir. Genelde yalnızca https:// gerekir ama http:// üzerindeki test ortamı açıkça eklenmelidir.
  • Yol kabul edilmez: https://example.com/shop reddedilir; origin yalnızca site adresidir.

Gerçek alan adınız listede yoksa widget başlamaz. Ziyaretçinin tarayıcısı "origin not allowed" reddini alır ve sohbet hiç açılmaz. Bu genellikle yeni alan adına taşınma, alt alan adı ekleme ya da ayrı adreste ikinci bir dil sürümü açma sonrasında ortaya çıkar; her biri kendi girdisini gerektirir.

Liste boşsa kısıtlama yoktur ve widget her yerden çalışır. Bunu "henüz yapılandırılmadı" olarak görün, bilinçli bir açıklık olarak değil: alan adlarınızı bilir bilmez listeye yazın.

Bu kısıtlama neyi korur, neyi korumaz

Korur: başka bir sitenin widget'ınızı kendi sayfasına gömmesini engeller. Aksi halde biri kodunuzu kendi sayfasına kopyalayabilir ve gerçek ziyaretçilerin tarayıcıları botunuzla yapılan yazışmaların içeriğini o siteye teslim ederdi. Liste tam olarak bunu kapatır.

Korumaz: anahtarı kopyalayıp platforma doğrudan — tarayıcıdan değil, örneğin bir betikle — istek gönderen birine karşı koruma değildir. Site adresini taşıyan başlığı tarayıcı ekler; tarayıcı dışında çalışan bir program onu göndermeyebilir ya da istediğini gönderebilir. Bu yüzden listeyi bir gömme kısıtlaması olarak görün, bir güvenlik sınırı olarak değil. Kötüye kullanıma karşı sizi platformun hız sınırları ve diyalog denetimi korur, bu liste değil.

Görünüm

Widget → Görünüm bölümünde şunlar ayarlanır:

  • Konum — düğme sol ya da sağ alt köşede.
  • Vurgu rengi — düğmenin ve sohbet öğelerinin rengi. Widget yabancı durmasın diye markanızın rengini kullanın.
  • Sohbet adı — başlatma düğmesinin etiketi ve sohbet panelinin başlığı. Genelde şirket adı ya da botun kendini tanıttığı ad.

Yanında bir önizleme vardır: sonucu kaydetmeden önce gösteren canlı bir widget.

Widget'ta henüz karşılama mesajı yok: yalnızca bu üç ayar var. İlk mesajı bot, ziyaretçinin yazdığına yanıt olarak, olağan tepkilerinize göre gönderir.

Değişiklikler siteye kendiliğinden ulaşır: widget ayarlarını sayfa yüklenirken okur, yapıştırılan kodu düzenlemek hiç gerekmez.

Ziyaretçiler anonimdir

Ziyaretçi yazmak için hiçbir şey doldurmaz. İlk açılışta widget platformdan anonim bir ziyaretçi kimliği alır ve tarayıcıda saklar; böylece kişi siteye döndüğünde boş bir sohbet değil, önceki yazışmasını görür.

Bundan şu sonuçlar çıkar:

  • Diyaloglarda bu ziyaretçi anonim görünür: kendisi yazmadıkça adı, telefonu ve e-postası yoktur.
  • Kimlik belirli bir tarayıcıda yaşar. Başka tarayıcı, başka cihaz ya da temizlenmiş site verileri yeni bir ziyaretçi ve temiz bir geçmiş demektir.
  • Anonim bir ziyaretçi, zaten tanıdığınız bir müşteriyle — örneğin üye alanınızda oturum açmış bir kullanıcıyla — eşleştirilebilir. Nasıl yapılacağı bir sonraki bölümde.

Bir ziyaretçiyi kendi kullanıcınıza bağlama

Ziyaretçi sitenizde zaten oturum açmışsa, platformaya kim olduğunu söyleyebilirsiniz. Bağlamadan sonra yazışma anonim olmaktan çıkar: o kişinin profiliyle birleştirilir ve önceki anonim mesajları kaybolmaz.

Kanıtı üreten bir işlevle yapılan tek bir çağrı yeter:

mybot.identify(async (visitorId) => {
  const res = await fetch("/mybot-sign", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ userId: currentUser.id, visitorId }),
  });
  return res.json(); // { userId, signature, expiresAt }
});

Widget, işlevinizi bu tarayıcı için geçerli anonim ziyaretçi kimliği olan visitorId ile çağırır — yalnızca widget'ın bildiği tek değerdir bu — ve işlevin { userId, signature, expiresAt } döndürmesini ya da buna çözümlenmesini bekler. İşlevinizin tek görevi visitorId'yi, oturum açmış kullanıcının kimliğiyle birlikte (yukarıdaki currentUser.id, bu sizin sitenizde ne ise odur) kendi sunucunuza iletmek ve sunucunuzun döndürdüğü şeyi olduğu gibi geri vermektir. Gerçek imzalama bu işlevde değil, sunucunuzda gerçekleşir — aşağıya bakın.

İki nedenden dolayı önceden hesaplanmış bir değer ya da visitorId'yi doğrudan okumanın bir yolu değil, bir geri çağırma işlevi:

  • Zamanlama. Widget, visitorId'yi başlarken eşzamansız olarak üretir — yükleyici betiği çalıştığı anda bu değer henüz yoktur ve mybot.identify'ın kendisi de ancak bu işlem bittikten sonra kurulur (ayrıntılar aşağıda). Böylece sayfanız mybot.identify'ı çağırabildiği anda, işlevinizin aldığı kimlik garantili olarak gerçektir. Sıradan bir getter bu garantiyi sağlamazdı: sayfanın onu bir satır erken okuyup hiçbir şey alamamasına ve hiçbir ipucu olmadan hiç doğrulanmayan bir imza üretmesine hiçbir şey engel olmazdı.
  • Kapsam. Kendi sayfa kodunuzun visitorId'yi elle tutması, saklaması ya da taşıması hiç gerekmez — yalnızca bu tek işlevin içinde, tek ihtiyacı olan çağrı için var olur.

Widget'tan çıktığı andan itibaren visitorId bir taşıyıcı yetkisidir (bearer capability): onun için bir imza elde edebilen herkes o ziyaretçinin oturumuyla birleştirilebilir. Yalnızca kendi sunucunuza, kendi kimlik doğrulamalı isteğinizle gönderin, başka hiçbir yere değil — loglamayın, üçüncü taraflara iletmeyin, istemci tarafı bir analitik çağrısına koymayın.

İmza yalnızca kendi sunucunuzda hesaplanır

Yukarıdaki işlevinizin içinde kendi sunucunuz — asla tarayıcı değil — imzayı hesaplar: widget gizli anahtarıyla hesaplanmış HMAC-SHA256 değeri; onaltılık gösterimde ilk 32 karakter, tek bir mesajda birleştirilmiş üç değerden. Aynı formül panelde gizli anahtarın yanında, "Signing algorithm" başlığı altında gösterilir:

signature = hex(HMAC-SHA256(key: secret, message: userId + "\n" + visitorId + "\n" + expiresAt)).slice(0, 32)

Yukarıdaki her + "\n" +, parçalar arasında gerçek bir satır sonu karakteridir, ters eğik çizgi ve n harfinden oluşan iki karakter değil. HMAC fonksiyonunuz mesajı tek bir dize olarak alıyorsa, üç parçayı gerçek bir satır sonuyla birleştirin — aralarında satır sonu olmadan yapılan üç ayrı .update() çağrısı farklı, yanlış bir mesajın özetini alır.

Üç parça:

  • userId — oturum açmış kullanıcının kimliği; sunucunuzun yukarıdaki işlevden aldığı ve yanıtında geri döndürdüğü aynı değer.
  • visitorId — işlevinizin argüman olarak aldığı ve değiştirmeden sunucunuza ilettiği anonim ziyaretçi kimliği.
  • expiresAt — tam olarak bu imzanın geçerli kalacağı ana kadar, sunucunuzun imzalarken ürettiği saniye cinsinden bir unix zaman damgası (milisaniye değil). Platform, expiresAt'i zaten geçmişte olan bir çağrıyı ve 24 saatten fazla ileride olan bir çağrıyı reddeder — imzayı işlevinizden döndürmeden hemen önce hesaplayın, sonraki istekler için bir kez hesaplayıp önbelleğe almak yerine.

Bu son kullanma süresi, değişikliğin ikincil bir ayrıntısı değil, asıl noktasıdır. Önceki formül yalnızca kullanıcı kimliğini kapsıyordu; bu yüzden bir kez ele geçirilen imza — bir yerde loglanmış, trafikten yakalanmış, nasıl olursa olsun — sonsuza dek geçerli kalıyor ve yalnızca verildiği kişi için değil, herhangi bir ziyaretçi için de işe yarıyordu. Böyle bir imzayı ele geçiren biri onu tamamen farklı bir tarayıcıda yeniden oynatabilir, platform da bir yabancının anonim gezinme geçmişini gerçek bir müşterinin profiliyle birleştirebilirdi. İmzayı belirli bir visitorId'ye bağlamak ve kısa bir ömür vermek bu açığın iki ucunu da kapatır: imza yalnızca verildiği oturum için doğrulanır, başka hiçbiri için değil, ve expiresAt geçtiğinde tamamen doğrulanmaz hâle gelir — yani sızan bir imza bile kalıcı değil, tek bir oturuma özgü, kısa ömürlü bir risk olarak kalır.

Üç değeri de kendi sunucunuzda hesaplayın ve işlevinizden hazır olarak döndürün. Bu bir formalite değildir: imzayı tarayıcıda hesaplamak için gizli anahtarı oraya göndermeniz, yani sayfanın her ziyaretçisine teslim etmeniz gerekirdi. Ondan sonra herkes sizin herhangi bir müşteriniz gibi görünüp onun yazışmasını okuyabilirdi. İmzayı (ve hesaplandığı visitorId/expiresAt'i) tarayıcıya geri vermek güvenlidir, gizli anahtarı vermek değil.

Çağrının kendisi ekranda hiçbir şey göstermez: bağlama sunucu tarafında ve sessizce olur. İşleviniz hata fırlatırsa ya da promise'i reddedilirse, ya da platform elde edilen imzayı reddederse — tutmazsa, ya da expiresAt eksikse, zaten geçmişteyse ya da 24 saatten fazla ileride ise — bunun ötesinde hiçbir şey olmaz: ziyaretçi bir şey fark etmez ve anonim olarak yazmayı sürdürür.

mybot.identify hemen var olmaz — widget'ın ana paketi, gerçek bir visitorId ile birlikte yüklendikten sonra ortaya çıkar (yukarıdaki "Zamanlama"ya bakın). Onu sayfa yükleme işleyicisinden çağırın, <head> içindeki ilk satırdan değil.

Gizli anahtar nerede ve nasıl değiştirilir

Widget gizli anahtarı, imzalarken kullandığınız anahtardır. Widget ayarlarında, "identify() secret" bölümünde durur. Bölüm widget'ın henüz bağlanmadığını söylüyorsa önce web kanalını bağlayın; gizli anahtar onunla birlikte gelir.

Gösterme. "Reveal secret" düğmesi değeri getirir. Değer açık metin olarak çıkmaz: önce noktalar görürsünüz, karakterleri ayrı bir "Show" anahtarı gösterir ("Mask" yeniden gizler). Yanında, değeri görünümden kaldıran "Clear from screen" düğmesi vardır.

İstediğiniz kadar gösterebilirsiniz ve göstermek hiçbir şeyi geçersiz kılmaz: gizli anahtar, ekranı kapattıktan sonra da geçerli kalır. Bunun nedeni, özetlenerek değil şifrelenerek saklanmasıdır — platformun her imzayı doğrulamak için gerçek değere ihtiyacı vardır. Altı ay sonra yeni bir arka uç yayına alıyorsanız, gelip yeniden okuyun.

Kopyaladıktan sonra arkanızı kendiniz toplayın. Panoyu platform temizleyemez: tarayıcıdan bunu güvenilir biçimde yapmak mümkün değil, bu yüzden söz de vermiyoruz. İşiniz bitince değeri ekrandan kaldırın ve panoyu elle temizleyin, özellikle ortak kullanılan bir bilgisayarda.

Değiştirme. Onay adımı olan "Rotate secret" düğmesi. Bu anında bozan bir işlemdir: yeni gizli anahtar var olduğu anda eskisi doğrulamayı bırakır. Örtüşme penceresi yoktur; iki anahtarın birlikte çalıştığı bir an bulunmaz.

Bozulan şey tam olarak ziyaretçilerin kullanıcılarınıza bağlanmasıdır. Konuşmalar kesintiye uğramaz — ziyaretçiler yazmayı ve yanıt almayı sürdürür, yalnızca anonim olarak — ta ki arka ucunuz yeni anahtarla imzalamaya başlayana kadar. Kurulum kodu ve izin verilen alan adları listesi etkilenmez; sitenizde değiştirilecek bir şey yoktur.

Bu yüzden bilinçli değiştirin: önce yeni değeri taşıyan arka uç dağıtımını hazırlayın, ancak ondan sonra "Rotate secret" düğmesine basın. Ne olacağını görmek için basmak kötü bir fikirdir. Yeni değer, değişimden hemen sonra ekranda gösterilir; böylece hemen kopyalayabilirsiniz.

Widget sayfada nasıl davranır

Widget, sitenizle çakışmayacak biçimde kasıtlı olarak tasarlanmıştır:

  • Yalıtılmış bir kapsayıcıda (kapalı Shadow DOM) yaşar. Sizin stilleriniz içeri girmez, widget'ın stilleri sayfaya sızmaz. Yan etkisi: widget'ı kendi CSS'inizle yeniden biçimlendiremezsiniz — görünüm ayarlarını kullanın.
  • Kapsayıcı ekranı kaplar ama tıklamaları yakalamaz: tıklamalar sayfaya geçer, yalnızca düğme ve sohbet paneli tepki verir.
  • Widget her zaman içeriğinizin üstündedir; kendi katmanlarınız onu örtemez.
  • Widget içindeki her hata içeride kalır: en kötü ihtimalle sohbet düğmesi çalışmaz, siteniz çalışmaya devam eder. Widget görünmüyorsa tarayıcı konsoluna bakın — neredeyse her zaman CSP ya da listede eksik bir alan adıdır.

Widget görünmüyorsa

Sırayla ilerleyin:

  1. Sayfa kaynağını açın; her iki etiketin yerinde olduğunu ve anahtarın boş olmadığını doğrulayın.
  2. Site adresinin listedekiyle birebir aynı olduğunu, https:// ve www dahil, doğrulayın.
  3. Tarayıcı konsoluna bakın: Content Security Policy mesajı, platformun adresine sitenizin CSP'sinde izin verilmesi gerektiği anlamına gelir.
  4. Bir reklam engelleyicinin widget'ı kaldırmadığından emin olun — eklentisiz gizli pencerede deneyin.

Sırada ne var