Web sitesi bileşeni

Bu bileşen, ziyaretçilerin web sitenizde gördüğü sohbet arayüzüdür. Yayınladığınız botu yükler ve tüm sohbeti tarayıcıda yürütür. Dil modeli kullanmaz, üçüncü taraflara istek göndermez ve sıkıştırıldıktan sonra yaklaşık 22KB boyutundadır. Temsilciyle canlı sohbet, yalnızca etkinleştirdiğinizde ayrı bir dosyadan yüklenir.

Kurulum

Bu satırı, botun görünmesini istediğiniz her sayfada </body> etiketinden önce yapıştırın. Yönetim panelindeki Kurulum sayfasında bu satırı kendi anahtarınızla birlikte bulabilirsiniz.

<script src="https://cdn.kavchat.com/v1/kavchat.js" data-key="pk_live_..." async></script>

Açık anahtarı (pk_live_...) sayfaya ekleyebilirsiniz. Gizli anahtarı (sk_live_...) ise asla sayfaya eklemeyin.

Öznitelikler

<script
  src="https://cdn.kavchat.com/v1/kavchat.js"
  data-key="pk_live_..."
  data-locale="he"
  data-user-token="<identity JWT>"
  data-user-name="Dana"
  data-open="false"
  async></script>

JavaScript API

Betik, window.Kavchat nesnesini oluşturur:

Kavchat.init({
  publicKey: 'pk_live_...',
  apiBase: 'https://api.kavchat.com', // optional
  locale: 'he',                       // optional
  userToken: '<identity JWT>',        // optional
  userName: 'Dana',                   // optional
  open: false,                        // optional
  onScreen(screen, targetId) {},      // optional: "screen" buttons in your scripts
  onEvent(event) {},                  // optional: ready, unavailable, open, close, effect, ticket
});
Kavchat.open();
Kavchat.close();
Kavchat.toggle();
Kavchat.setUser({ token: '<identity JWT>', name: 'Dana' }); // on login; setUser(null) on logout
Kavchat.offset({ bottom: 80 });       // lift the launcher, e.g. above a cookie banner; offset(null) resets
Kavchat.destroy();

Betik etiketinde data-key varsa init çağrısı gerekmez. init yeniden çağrıldığında çalışan bileşen yenisiyle değiştirilir.

Betik yüklenmeden API'yi çağırma

Betik etiketi async olduğu için kodunuz önce çalışabilir. Bir kuyruk oluşturup çağrıları bu kuyruğa ekleyin. Bileşen yüklendiğinde bunları sırayla çalıştırır. init her zaman ilk sırada çalışır ve ayarları, etiketteki özniteliklerden önceliklidir.

<script>
  window.Kavchat = window.Kavchat || { q: [] };
  Kavchat.q.push(['init', { publicKey: 'pk_live_...', onScreen: function (s, id) { location.href = '/' + s + '/' + id; } }]);
  Kavchat.q.push(['setUser', { token: '<identity JWT>', name: 'Dana' }]);
</script>
<script src="https://cdn.kavchat.com/v1/kavchat.js" async></script>

Kuyruktaki her öğe [methodName, ...args] biçimindedir. Betik yüklendikten sonra da Kavchat.q.push(...) çalışmaya devam eder ve çağrıyı hemen yürütür. Böylece aynı kod her iki durumda da kullanılabilir.

Çerez bandı için alan

Sitenizde çerez bandı gibi ekranın altına sabitlenmiş bir öğe varsa düğmeyi, pencereyi ve baloncukları bu öğenin üzerine taşıyabilirsiniz. Bunun için iki yöntem vardır: --kavchat-bottom adlı CSS değişkeni veya piksel cinsinden bir sayı ya da 5rem gibi bir uzunluk değeri alan Kavchat.offset komutu. Kaydırma miktarı, yönetim panelinde belirlenen yüksekliğe eklenir. Çerez bandı kapandığında değişkeni kaldırın veya offset(null) çağrısını yapın. Her iki yöntem de katı CSP kuralları olan sitelerde çalışır. Telefonda pencere tam ekran açılır ve kaydırılmaz.

/* while your cookie banner is shown */
body.cookie-banner-open { --kavchat-bottom: 80px; }

// works before or after the widget script loads
window.Kavchat = window.Kavchat || { q: [] };
Kavchat.q.push(['offset', { bottom: banner.offsetHeight + 12 }]);

// after the visitor makes a choice
Kavchat.q.push(['offset', null]);

Olaylar

onEvent işlevi aşağıdaki olaylardan birini alır:

Kavchat.init({
  publicKey: 'pk_live_...',
  onEvent(event) {
    if (event.type === 'ready') console.log('Bot version', event.version, event.offline ? '(offline copy)' : '');
    if (event.type === 'ticket') console.log('Request opened', event.number);
  },
});

Senaryo eylemleri

• Destek talebi: Sohbet içinde destek talebi formunu açar. Sohbet dökümü talebe eklenir.
• Bağlantı: https: ve tel: bağlantılarını yeni sekmede açar (rel="noopener noreferrer"). Diğer bağlantı türleri açılmaz.
• Ekran: Tanımladığınız onScreen(screen, targetId) işlevini çağırır. Bu işlev yoksa düğme web sitesinde hiçbir işlem yapmaz.

Düzenleyicideki ekran listesi

Uygulamanızın açabildiği ekranları Kavchat.init içindeki screens seçeneğinde bir kez tanımlayın. SDK listeyi Kavchat'e kendisi gönderir. Senaryo düzenleyicisi de serbest metin alanı yerine bu ekranları adlarıyla bir açılır listede sunar. Ekran bir öğe kimliği gerektiriyorsa düzenleyici bunu da ister ve tanımlanmamış bir ekrana yönlendiren düğmeler için uyarı verir. Ekran listesini yönetim paneline elle girmeniz gerekmez.

Kavchat.init({
  publicKey: 'pk_live_...',
  screens: [
    { id: 'orders', label: 'My orders' },
    { id: 'product', label: 'Product page', needsTarget: true }, // the button also carries a product id
  ],
  onScreen(screen, targetId) {
    location.href = targetId ? `/${screen}/${targetId}` : `/${screen}`;
  },
});

• id, onScreen işlevine iletilen değerdir: Latin harfleri, rakamlar, _, . ve - kullanılabilir; en fazla 40 karakterdir. label, yöneticinin gördüğü addır; en fazla 60 karakterdir. En fazla 100 ekran tanımlanabilir. Geçersiz kayıtlar ve yinelenen kimlikler atlanır.
• needsTarget: Düğme ayrıca bir öğe kimliği (örneğin ürün kimliği) taşır. Bu kimlik onScreen işlevine targetId olarak iletilir.
• Liste, sürüm yüklendikten sonra arka planda, yalnızca değiştiğinde veya haftada bir gönderilir. Gönderim başarısız olursa kullanıcıya yansıtılmaz ve bir sonraki açılışta yeniden denenir. Kullanıcı hiçbir şey görmez.
• Kaydedilen ekranlar, yönetim panelinde Bot, Ayarlar, "Uygulama ekranları" altında, her ekranı bildiren platformlarla birlikte görünür. Uygulamadan kaldırdığınız bir ekranı buradan silebilirsiniz.

Kullanıcılarınızı tanımlama

Sohbetlere ve destek taleplerine kendi kullanıcı kimliğinizi eklemek veya botu yalnızca test kullanıcılarına göstermek için sunucunuzda bir JWT imzalayıp data-user-token ya da userToken ile iletin. Kullanıcı oturum açtığında veya kapattığında Kavchat.setUser(...) işlevini çağırın. Bileşen, belirteci her çağrıda Authorization: Bearer <token> başlığıyla gönderir. Oturum açmış kullanıcılar e-posta veya telefon bırakmadan destek talebi oluşturabilir. Belirtecin nasıl oluşturulacağını öğrenmek için: Kullanıcıları tanımlama.

İçerik Güvenliği Politikası (CSP)

Widget, 'unsafe-inline' ve 'unsafe-eval' olmadan, katı bir CSP uygulanan sitelerde çalışır. Yalnızca şu iki kaynağımıza izin vermeniz yeterlidir:

script-src https://cdn.kavchat.com;
connect-src https://api.kavchat.com;

Stiller, Shadow DOM içinde constructable stylesheets olarak yüklenir. Bu nedenle style-src yönergesini değiştirmeniz gerekmez. Botun kendi görseli varsa veya senaryolarda görseller kullanılıyorsa, bu görsellerin yüklendiği sunucuyu img-src yönergesine ekleyin. Widget başka hiçbir kaynaktan içerik yüklemez ve iframe açmaz.

Temsilciyle canlı sohbet

Web sitenizde herhangi bir ayar yapmanız gerekmez. Yönetim panelinde temsilciyle canlı sohbeti etkinleştirdiğinizde bileşen, kavchat.js ile aynı klasörden ve aynı sürümde ek bir dosya yükler: kavchat-live.js. Temsilciyle canlı sohbet kullanmayan siteler bu dosyayı hiç indirmez.

• Seçenek: "Ekibe ulaşın" seçeneğinin yanında "Temsilciyle görüşün" seçeneği, yalnızca sunucu müsait bir temsilci olduğunu doğruladığında görünür. Çalışma saatleri dışında veya tüm temsilciler meşgulken yalnızca destek talebi formu gösterilir. Yanında kısa bir açıklama ve biliniyorsa ekibin ne zaman döneceği yer alır. Aylık kota dolduğunda form açıklama olmadan gösterilir.
• İstek: Ziyaretçiler, bir temsilcinin zamanında müsait olamaması ihtimaline karşı e-posta veya telefon bırakır. İsterlerse adlarını ve ilk mesajlarını da ekleyebilirler. Birden fazla departman açıksa departman seçerler. Kimliği doğrulanmış kullanıcıların (userToken) iletişim bilgilerini doldurması gerekmez. Hiçbir temsilci sohbeti kabul edemiyorsa destek talebi formu, önceden girilen bilgilerle açılır.
• Bekleme: "Temsilci bekleniyor" mesajı, belirlediğiniz bekleme süresinin sonuna kadar geri sayım ve "Bunun yerine mesaj bırakın" ile "Sohbeti sonlandırın" düğmeleri gösterilir. Ziyaretçiler beklerken de yazabilir. Süre dolduğunda sohbet otomatik olarak destek talebine dönüşür. Ziyaretçiye talep numarası ve hiçbir temsilcinin zamanında müsait olamadığını belirten bir açıklama gösterilir.
• Sohbet: Temsilcinin adı, mesajlar, yazıyor göstergesi, başka bir temsilciye aktarım ve sohbeti sonlandırma. Sunucudan gelen her şey HTML veya bağlantı içermeyen düz metin olarak gösterilir. Ekran okuyucular yeni mesajları seslendirir. Pencere kapalıyken yüzen düğmenin üzerinde bir nokta görünür.
• Gerçek zamanlı iletişim: Bağlantı Server-Sent Events üzerinden kurulur. Bağlantı koparsa bileşen giderek uzayan aralıklarla yeniden bağlanmayı dener ve kaçırılan tüm verileri alır. Böylece hiçbir mesaj kaybolmaz veya iki kez gösterilmez. Bu bağlantıyı engelleyen ağlarda bileşen tekrarlanan sorgulara (long-poll) geçer. Her mesajın bir kimliği vardır; bu nedenle yeniden deneme, yinelenen mesaj oluşturmaz. Gönderilemeyen mesaj işaretlenir ve dokunarak yeniden gönderilebilir.
• Yeniden yükleme: Sohbete erişim yetkisi, açık anahtar ve sohbete göre localStorage içinde saklanır; asla URL'de tutulmaz. En fazla 12 saat veya sohbet bitene kadar geçerlidir. Böylece sayfa yeniden yüklendiğinde ya da başka bir sayfaya geçildiğinde sohbetin tamamı geri yüklenir: önce botla yapılan bölüm, ardından temsilciyle yapılan bölüm.
• Preflight olmadan: Çağrılar özel başlıklar olmadan gönderilir. İstek gövdesi, text/plain olarak gönderilen JSON verisidir.

Yapay zekâ yanıtları (Premium)

Web sitenizde herhangi bir ayar yapmanız gerekmez. Yönetim panelinde yapay zekâ yanıtlarını etkinleştirdiğinizde (kendi yapay zekâ sağlayıcınızın anahtarıyla), hiçbir senaryonun yanıtlamadığı sorular Kavchat'e gönderilir. En fazla 20 saniyelik bekleme sırasında sohbette botun yazdığı gösterilir. Yanıt, arayüz dilinde küçük bir "Yapay zekâ yanıtı" etiketiyle düz metin olarak gösterilir. Altında, varsa ilgili konuya yönlendiren bir düğme ve "Ekibe ulaşın" düğmesi bulunur.

Yanıt yoksa, istek başarısız olursa, çok uzun sürerse veya sınır aşılırsa (her 15 dakikada sohbet başına 10 yanıt) sohbet, her zamanki "Yanıt bulamadım" mesajını gösterir. Soru, yanıtlanamayan sorular raporunda yine yer alır. Yapay zekâ yanıtları da diğer mesajlar gibi sohbet kaydında saklanır.

Bileşenin çalışma şekli

• Yalıtım: Her şey Shadow DOM içinde gösterilir. Sitenizin CSS'i bileşeni, bileşenin CSS'i de sayfanızı etkilemez.
• Önbellek: Yayınlanan bot, ETag değeriyle birlikte açık anahtara göre localStorage içinde saklanır. Her yüklemede If-None-Match başlığı gönderilir. Hiçbir şey değişmediyse sunucu 304 yanıtı verir. Ağ bağlantısı yoksa bileşen kayıtlı kopyayı kullanır ve bunu belirten bir bildirim gösterir.
• Sohbetler: Rastgele bir sohbet kimliği sessionStorage içinde saklanır. Böylece sayfalar arasında geçiş yapıldığında aynı sohbet devam eder.
• Temsilciyle canlı sohbet: Açık sohbet localStorage içinde saklanır ve sonraki sayfada geri yüklenir.
• Veriler: Sohbetin akışı, her eylemden yaklaşık 2 saniye sonra ve sayfa gizlendiğinde raporlanır.
• Kavchat rozeti: Tüm planlarda gösterilir. Premium'da bot ayarlarından gizleyebilirsiniz.
• Erişilebilirlik: Pencere, etiketli bir iletişim kutusudur. Odak pencereye taşınır ve kapanınca geri döner. Esc pencereyi kapatır. Düğmeler gerçek düğme öğeleridir. Botun yeni mesajları seslendirilir ve ziyaretçinin tercihine göre animasyonlar azaltılır.

npm ile kurulum

Tek sayfalı bir uygulamada betik etiketini yüklemek yerine bileşeni kendi kodunuzla paketleyebilirsiniz:

yarn add @kavchat/widget
# or: npm install @kavchat/widget

import { createWidget } from '@kavchat/widget';

const widget = createWidget({ publicKey: 'pk_live_...' });
await widget.ready;
widget.open();