Kavchat by maxsave
Rehber menüsü

iOS

Kavchat Swift paketi, senaryoya dayalı destek botunu SwiftUI ve UIKit bileşenleriyle iOS uygulamanıza ekler. Yanıtlar öngörülebilirdir ve son yayımlanan sürüm üzerinden internet bağlantısı olmadan da çalışır. iOS 15 veya üzeri gerekir.

Pakette iki ürün bulunur: konuşma motorunun UIKit içermeyen Swift sürümü KavchatEngine ve ağ iletişimini, cihazdaki önbelleği ve arayüzü içeren Kavchat. Arayüz bileşenleri: KavchatChatView (SwiftUI), KavchatLauncher ve KavchatViewController (UIKit).

Kurulum

Xcode'da Swift Package Manager ile: File > Add Package Dependencies yolunu izleyin ve depo adresini girin:

Package URL
https://bitbucket.org/maxsave/kavchat-ios.git

Veya Package.swift dosyasında:

Package.swift
.package(url: "https://bitbucket.org/maxsave/kavchat-ios.git", from: "0.0.11"),
// ...
.product(name: "Kavchat", package: "kavchat-ios"),

SDK, MIT lisansıyla sunulan açık kaynaklı bir projedir: bitbucket.org/maxsave/kavchat-ios.

Yapılandırma

configure metodunu mümkün olduğunca erken, yalnızca bir kez çağırın. Örneğin App içindeki init metodunda veya application(_:didFinishLaunchingWithOptions:) içinde:

Swift
import Kavchat

Kavchat.configure(publicKey: "pk_live_...")            // the public key from the dashboard
// Optional:
// Kavchat.configure(publicKey: "pk_live_...", apiBase: "https://api.kavchat.com", locale: "he")

Açık anahtarı uygulamaya ekleyebilirsiniz. Gizli anahtarı (sk_live_...) ise hiçbir zaman uygulamaya eklemeyin.

SwiftUI

Yönetim panelinde seçilen köşede duran ve sohbeti bir pencerede (sheet) açan yüzen düğme:

SwiftUI
ContentView()
    .kavchatLauncher()

Düğmeyi kendiniz de konumlandırabilir veya sohbeti kendi ekranınıza gömebilirsiniz:

SwiftUI
KavchatLauncher()
KavchatChatView()                                      // full chat, no close button
KavchatChatView(onClose: { showChat = false })         // with a close button

Yüzen düğmenin açtığı pencereyi kod üzerinden Kavchat.open() ve Kavchat.close() ile açıp kapatabilirsiniz.

UIKit

UIKit
Kavchat.present(from: self)                            // modal, with a close button
// or
let chat = KavchatViewController(showsCloseButton: false)
navigationController?.pushViewController(chat, animated: true)

Kimlik belirteci

Oturum açmış kullanıcıyı, sunucunuzun gizli anahtarla imzaladığı bir JWT ile tanımlayın (bkz. Kullanıcıları tanımlama). Belirteç, Authorization: Bearer <token> başlığında gönderilir. Kimliği doğrulanan kullanıcı, yalnızca test kullanıcılarına açık sürümleri görebilir ve e-posta ya da telefon bilgisi vermeden iletişim formunu gönderebilir.

Swift
Kavchat.setUser(token: identityToken, name: "Dana")    // after login
Kavchat.setUser(token: nil)                            // after logout

Kullanıcı değiştirildiğinde sürüm yeniden yüklenir ve yeni bir konuşma başlar. Böylece bir kullanıcının konuşması başka bir kullanıcıya gösterilmez.

Uygulama ekranları: onScreen

Senaryodaki screen türündeki bir düğme, uygulamanızdan ekranlarından birini açmasını ister. Ekranın görünmesi için önce sohbet penceresi kapanır:

Swift
Kavchat.onScreen = { screen, targetId in
    router.open(screen, id: targetId)                  // e.g. "orders", "42"
}

Bir işleyici tanımlanmadığında bu düğmeler hiçbir işlem yapmaz. link düğmeleri yalnızca https ve tel bağlantılarını açar. Veri analizi için Kavchat.onEvent; ready, unavailable, open, close, effect ve ticket olaylarını bildirir.

Düzenleyicide ekran listesi

Uygulamanızın açabildiği ekranları Kavchat.configure(..., screens:) iç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. Bir ekran öğ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 girmek gerekmez.

Swift
Kavchat.configure(publicKey: "pk_live_...", screens: [
    KavchatScreen(id: "orders", label: "My orders"),
    KavchatScreen(id: "product", label: "Product page", needsTarget: true),  // needs a targetId
])
// or later: Kavchat.registerScreens([...])
  • id, onScreen metoduna iletilen değerdir: Latin harfleri, rakamlar, _, . ve - içerebilir, en fazla 40 karakter olabilir. label, yöneticinin gördüğü addır ve en fazla 60 karakter olabilir. 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 metoduna 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 hatası kullanıcıya yansıtılmaz ve bir sonraki açılışta yeniden denenir. Kullanıcıya hiçbir şey gösterilmez.
  • Kaydedilen ekranlar, her ekranı bildiren platformlarla birlikte yönetim panelinde Bot, Ayarlar, "Uygulama ekranları" altında görünür. Uygulamadan kaldırdığınız bir ekranı buradan silebilirsiniz.

Renkler

Renkler yönetim panelinden alınır (primaryColor). Marka renginin üzerindeki metin, WCAG kontrastına göre beyaz veya siyaha yakın olur. Beyaz zemin üzerinde metin için fazla açık kalan bir renk, bağlantılarda ve düğmelerde siyaha yakın bir renkle değiştirilir. Bot adı, alt başlık, görsel ve yüzen düğmenin konumu (start veya end) da yönetim panelinden alınır. Böylece uygulama güncellenmeden değiştirilebilirler.

"Kavchat by maxsave altyapısıyla" rozeti, kavchat.com bağlantısıyla tüm planlarda gösterilir. Premium'da bu rozeti bot ayarlarından gizleyebilirsiniz.

Diller ve RTL

  • Arayüz dili, configure metoduna iletilen locale değeridir. Bu değer iletilmezse çevirisi mevcut olan cihaz dili kullanılır (he, en, ar, ru, es, fr, de, pt, it, tr). O da yoksa senaryo dili, son olarak İngilizce kullanılır.
  • Eşleştirme her zaman senaryonun dilinde yapılır (atlanan yaygın kelimeler ve İbranice ile Arapçadaki ön ekler).
  • İbranice ve Arapçada tüm sohbetin layoutDirection değeri sağdan sola olur. Hiçbir şey elle ters çevrilmez: bileşenleri bir kapsayıcıya yerleştiriyorsanız leading ve trailing kullanın.

Yapay zekâ yanıtları (Premium)

Uygulamada herhangi bir ayar yapmanız gerekmez. Yönetim panelinde yapay zekâ yanıtlarını etkinleştirdiğinizde (kendi yapay zekâ sağlayıcınıza ait anahtarla), hiçbir senaryonun yanıtlamadığı soru Kavchat'e gönderilir. En fazla 20 saniyelik bekleme süresince 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 ait bir düğme ve "Ekibe ulaşın" düğmesi yer alır.

Yanıt yoksa veya istek başarısız olursa, çok uzun sürerse ya da sınır aşılırsa (her 15 dakikada konuşma başına 10 yanıt), sohbet standart "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 kaydedilen konuşmada saklanır.

Temsilciyle canlı sohbet

Uygulamada herhangi bir ayar yapmanız gerekmez. Yönetim panelinde temsilcilerle canlı sohbeti etkinleştirdiğinizde uygulamadaki sohbet, web sitesindeki sohbet bileşeniyle aynı şekilde çalışır.

  • Bu seçenek yalnızca yayımlanan sürümde temsilcilerle canlı sohbet etkinse gösterilir. Bot "Ekibe ulaşın" seçeneğini gösterdiğinde SDK, müsait bir temsilci olup olmadığını kontrol eder. Sonuç 30 saniye boyunca saklanır. Müsait temsilci varsa bu seçeneğin önünde "Temsilciyle görüşme" düğmesi görünür. Yoksa yalnızca iletişim formu gösterilir. Formun üstünde nedeni açıklayan kısa bir satır yer alır: çalışma saatleri dışında olunduğu (yeniden hizmet verilecek saatle birlikte) veya tüm temsilcilerin meşgul olduğu belirtilir.
  • Sohbetten önce kısa bir form doldurulur: ad, e-posta veya telefon, departman (yalnızca birden fazla açık departman varsa) ve ilk mesaj (isteğe bağlı). Misafirlerin e-posta veya telefon bilgisi bırakması gerekir. Kimlik belirteciyle tanımlanan kullanıcılardan bu bilgiler istenmez. Form gönderilirken artık müsait temsilci yoksa iletişim formu, girilmiş bilgilerle açılır.
  • Beklerken konuşmanın destek talebine dönüşmesine kalan süre ve "Beklemek yerine mesaj bırakın" düğmesi gösterilir. Bekleme süresi yönetim panelinden belirlenir; varsayılan süre 2 dakikadır. Beklerken de mesaj yazılabilir ve temsilci bu mesajları görür. Süre dolana kadar hiçbir temsilci müsait olmazsa konuşma normal bir destek talebi olarak kaydedilir ve talep numarası gösterilir.
  • Sohbet sırasında temsilcinin adı, bir temsilci katıldığında bildirim (başka bir temsilciye aktarıldıktan sonra da), temsilci yazarken bir gösterge ve sohbeti bitirme düğmesi görünür. Mesajlar yalnızca düz metin içerir, en fazla 2.000 karakter olabilir ve bağlantı içermez. Sunucuya henüz ulaşmamış mesajlar "Gönderiliyor..." olarak işaretlenir. Gönderim birkaç kez başarısız olursa yeniden denemek için mesaja dokunabilirsiniz. Yeniden deneme, yinelenen bir mesaj oluşturmaz.
  • Her bağlantı kesintisinden sonra SDK kısa bir süre bekler, kaçırılan verileri alır ve yeniden bağlanır. Bekleme süresi giderek uzar. Mesajlar her zaman sıralı ve tekrarsız gösterilir. Sürekli bağlantı kurulamazsa (örneğin kurumsal bir proxy arkasında), SDK geçici olarak sunucuyu belirli aralıklarla kontrol etmeye geçer.
  • Uygulama arka plana geçtiğinde bağlantı kapanır. Uygulamaya dönüldüğünde SDK kaçırılan verileri alır ve yeniden bağlanır. Açık bir sohbet, 12 saat geçmediği sürece uygulama kapatılıp yeniden açıldıktan sonra da devam eder.
  • Bu sürümde anlık bildirimler yoktur. Mesajlar yalnızca uygulama açıkken gelir. Uygulama arka plandayken gönderilen yanıt, uygulamaya dönüldüğünde hemen görünür.
  • Sohbete erişim bilgileri yalnızca bellekte ve cihazın Keychain'inde saklanır. UserDefaults içinde, adreste veya günlüklerde saklanmaz. Sohbet sona erdiğinde, destek talebine dönüştüğünde veya süresi dolduğunda bu bilgiler silinir. setUser ile kullanıcı değiştirildiğinde de silinir.

Temsilciye kullanıcının hangi ekrandan geldiğini belirtmek için Kavchat.shared.livePage kullanabilirsiniz.

Sorular, koşullar ve potansiyel müşteriler

Uygulamada herhangi bir ayar yapmanız gerekmez. Bir senaryo bilgi isteyebilir (ad, telefon, e-posta, sayı veya serbest metin), bilinen bilgilere göre nasıl ilerleyeceğini seçebilir ve potansiyel müşteri kaydı gönderebilir.

  • Uygun klavye: Bot yanıt beklerken metin alanında telefon, e-posta veya sayısal klavye açılır. Ad sorularında klavye, her kelimenin ilk harfini büyük yazar. Yanıt geçersizse bot sohbet dilinde kısa bir mesaj gösterir ve alan işaretlenir. Atlanabilir sorularda "Atla" düğmesi görünür. Desteklenen herhangi bir dilde "İptal" yazmak sorudan çıkılmasını sağlar.
  • Telefon: Başında + olmayan numaralarda çalışma alanının varsayılan ülkesi kullanılır (yönetim panelindeki ayarlardan belirlenir).
  • Potansiyel müşteri: Potansiyel müşteri adımı, "Gönder" ve "Hayır, teşekkürler" düğmeleriyle birlikte onay metnini, ardından da onay mesajını gösterir. Potansiyel müşteri kaydı cihazda kuyruğa alınır ve sunucuya gönderilir. İnternet bağlantısı yoksa veya sunucuya ulaşılamıyorsa gönderim yeniden denenir (bir sonraki açılışta ve reload() sonrasında da). Sunucu yinelenen kayıtları dikkate almaz.
  • Önceden doldurma: İletişim formu ve temsilciyle görüşme talebi formu, toplanan ad, e-posta ve telefon bilgileriyle doldurulur. Toplanan tüm değerler destek talebine veya temsilciyle görüşme talebine eklenir. Temsilciyle sohbet öncesi sorular (Premium), bağlantı kurulmadan önce sorulur.
  • Kimlik belirteci: setUser kullanıldığında belirteçteki name, email ve phone alanları ilgili soruların yanıtlarını doldurur ve bot bu soruları atlar.
  • Mevcut ekran: Koşullar mevcut ekranı kontrol edebilir. Kavchat.shared.livePage değerini ayarlayın (örneğin "checkout").

Toplanan değerler kişisel bilgidir. Cihazda kaydedilen konuşmada saklanır ve yalnızca potansiyel müşteri kayıtlarına, destek taleplerine ve temsilciyle yapılan sohbetlere gönderilir; raporlara hiçbir zaman gönderilmez.

Çevrimdışı çalışma ve önbellek

Son sürüm, ETag değeriyle birlikte UserDefaults içinde saklanır ve her açılışta If-None-Match (304) ile yeniden doğrulanır. İnternet bağlantısı yoksa kaydedilen kopya kullanılır ve bunu belirten bir mesaj gösterilir. Bot kapalıysa, yalnızca test kullanıcılarına açıksa veya kota dolmuşsa hiçbir şey gösterilmez. Açık bir konuşma, 30 dakikalık hareketsizliğe kadar saklanır. Böylece sohbetten veya uygulamadan çıkmak konuşmayı yeniden başlatmaz. Konuşmanın akışı, son işlemden iki saniye sonra ve uygulama arka plana geçer geçmez raporlanır.