Kavchat by maxsave
Rehber menüsü

Android

Kavchat Android kütüphanesi, senaryoya dayalı destek botunu uygulamanıza ekler. Jetpack Compose bileşenleri ve Views ile geliştirilen uygulamalar için bir Activity sunar. Yanıtlar öngörülebilirdir ve internet bağlantısı olmasa da son yayımlanan sürüm üzerinden çalışmaya devam eder. Android 6.0 (API 23) veya üzeri gerekir.

İki bileşen vardır: sohbet motorunun Android veya üçüncü taraf kütüphanelere bağımlılığı olmayan Kotlin/JVM sürümü kavchat-engine ve ağ iletişimini (HttpURLConnection), cihazdaki önbelleği (SharedPreferences), KavchatChat ve KavchatLauncher Compose bileşenlerini ve KavchatActivity bileşenini içeren kavchat.

Kurulum

Gradle (Kotlin DSL)
// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://jitpack.io")
    }
}

// app/build.gradle.kts
dependencies {
    implementation("com.kavchat:kavchat-android:0.0.11")
}

Kütüphane JitPack üzerinden sunulur. Bu nedenle JitPack deposunu google() ve mavenCentral() yanına bir kez ekleyin. SDK, MIT lisansıyla açık kaynak olarak sunulur: bitbucket.org/maxsave/kavchat-android.

Kütüphane, INTERNET iznini ve KavchatActivity bileşenini kendi manifest dosyasında tanımlar. Elle bir şey eklemeniz gerekmez.

Yapılandırma

Application.onCreate içinde configure metodunu bir kez çağırın:

Kotlin
class App : Application() {
    override fun onCreate() {
        super.onCreate()
        Kavchat.configure(this, publicKey = "pk_live_...")
        // Optional: Kavchat.configure(this, "pk_live_...", apiBase = "https://api.kavchat.com", locale = "he")
    }
}

Açık anahtarı uygulamanıza ekleyebilirsiniz. Gizli anahtarı (sk_live_...) ise asla uygulamaya eklemeyin.

Compose

Yönetim panelinde seçilen köşede görünen ve sohbeti tam ekran açan yüzen düğme:

Compose
KavchatOverlay(Modifier.fillMaxSize()) {
    AppContent()
}

Düğmeyi kendiniz de konumlandırabilir veya sohbeti kendi ekranınıza yerleştirebilirsiniz:

Compose
KavchatLauncher()                                    // com.kavchat.ui.KavchatLauncher
KavchatChat(Modifier.fillMaxSize())                  // full chat, no close button
KavchatChat(Modifier.fillMaxSize(), onClose = { navController.popBackStack() })

Yüzen düğmenin sohbetini koddan açıp kapatmak için Kavchat.controller.setPresented(true) ve setPresented(false) kullanın.

Views (uygulamanızda Compose olmadan)

Kotlin
Kavchat.open(context)                                // starts KavchatActivity

Java üzerinden: Kavchat.open(context);. Activity kendi içinde Compose kullanır, ancak uygulamanızın Compose kullanması gerekmez.

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 tanımlanmış kullanıcılar yalnızca test kullanıcılarına açık sürümleri görebilir ve e-posta veya telefon bilgisi vermeden destek talebi formunu gönderebilir.

Kotlin
Kavchat.setUser(token = identityToken, name = "Dana")   // after login
Kavchat.setUser(token = null)                           // after logout

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

Uygulama ekranları: onScreen

Senaryodaki screen türündeki bir düğme, uygulamadan ekranlarından birini açmasını ister. Ekranın görünmesi için önce sohbet (KavchatLauncher iletişim kutusu veya KavchatActivity) kapanır:

Kotlin
Kavchat.onScreen = { screen, targetId ->
    navController.navigate("$screen/${targetId.orEmpty()}")   // e.g. "orders", "42"
}

Bir işleyici tanımlanmazsa bu düğmeler hiçbir işlem yapmaz. link düğmeleri yalnızca https bağlantılarını (tarayıcıda) ve tel bağlantılarını (arama ekranında) açar. Veri analizi için Kavchat.onEvent; Ready, Unavailable, Open, Close, Effect ve Ticket olaylarını bildirir.

Düzenleyicideki ekran listesi

Uygulamanızın açabildiği ekranları Kavchat.configure(..., screens = ...) içinde bir kez tanımlayın (KavchatAppScreen türü). 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. Düzenleyici, ekran gerektiriyorsa öğe kimliği de ister ve tanımlanmamış bir ekrana yönlendiren düğmeler için uyarı verir. Ekran listesini yönetim paneline elle girmeniz gerekmez.

Kotlin
Kavchat.configure(
    this, publicKey = "pk_live_...",
    screens = listOf(
        KavchatAppScreen("orders", "My orders"),
        KavchatAppScreen("product", "Product page", needsTarget = true),   // needs a targetId
    ),
)
// or later: Kavchat.registerScreens(listOf(...))
  • id, onScreen metoduna iletilen değerdir: Latin harfleri, rakamlar, _, . ve - kullanılabilir; 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 değer 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 başarısız olursa kullanıcıya yansımaz ve bir sonraki açılışta yeniden denenir. Kullanıcıya hiçbir şey gösterilmez.
  • 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.

Renkler

Renkler yönetim panelinden alınır (primaryColor). Marka rengi üzerindeki metin, WCAG kontrastına göre beyaz veya siyaha yakın olur. Beyaz zemin üzerinde metin için fazla açık kalan renkler, bağlantılarda ve düğmelerde siyaha yakın bir renkle değiştirilir. Botun adı, alt başlığı, görseli ve yüzen düğmenin tarafı (start veya end) da yönetim panelinden alınır. Böylece uygulamayı güncellemeden değiştirilebilirler. Yüzeyler ve tipografi, uygulamanızın MaterialTheme ayarlarını kullanır.

"Kavchat by maxsave altyapısıyla" rozeti, kavchat.com bağlantısıyla tüm planlarda gösterilir. Premium planında 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). Ardından senaryo dili, son olarak da İngilizce kullanılır.
  • Senaryoyla eşleştirme her zaman senaryonun dilinde yapılır (atlanacak yaygın kelimeler ile İbranice ve Arapça ön ekler).
  • İbranice ve Arapçada tüm sohbetin LocalLayoutDirection değeri RTL olur. Hiçbir şey elle ters çevrilmez: Bileşenleri sarmalıyorsanız start ve end kullanın. Uygulamanızın manifest dosyasında android:supportsRtl="true" ayarını koruyun.

Yapay zekâ yanıtları (Premium)

Uygulamada yapılandırmanız gereken bir şey yoktur. Yönetim panelinden 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ırasında sohbet, botun yazdığını gösterir. Yanıt, arayüz dilinde küçük bir "Yapay zekâ yanıtı" etiketiyle düz metin olarak gösterilir. Altında, varsa ilgili bir konuya yönlendiren düğme ve "Ekibe ulaşın" düğmesi yer alır.

Yanıt yoksa ya da istek başarısız olursa, çok uzun sürerse veya sınıra ulaşırsa (her 15 dakikada sohbet başına 10 yanıt), sohbet standart "Yanıt bulamadım" mesajını gösterir. Soru yine de yanıtlanamayan sorular raporunda görünür. Yapay zekâ yanıtları da diğer mesajlar gibi kayıtlı sohbette saklanır.

Temsilciyle canlı sohbet

Uygulamada herhangi bir ayar yapmanız gerekmez. Yönetim panelinden 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 bir temsilci varsa bu seçeneğin önünde "Temsilciyle görüşün" düğmesi görünür. Yoksa yalnızca destek talebi formu gösterilir. Formun üstündeki kısa bir satırda nedeni açıklanır: çalışma saatleri dışında olunması (yeniden hizmet verilecek saatle birlikte) veya tüm temsilcilerin meşgul olması.
  • Sohbetten önce kısa bir form doldurulur: ad, e-posta veya telefon, departman (yalnızca birden fazla departman açıksa) ve ilk mesaj (isteğe bağlı). Misafirlerin e-posta veya telefon bilgisi vermesi gerekir. Kimlik belirteciyle tanımlanan kullanıcıların bunlardan herhangi birini vermesi gerekmez. Gönderim sırasında müsait temsilci kalmamışsa destek talebi formu, doldurulmuş bilgilerle açılır.
  • Beklerken sohbetin destek talebine dönüşmesine kalan süre ve "Bunun 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 dolmadan hiçbir temsilci müsait olmazsa sohbet normal bir destek talebi olarak kaydedilir ve talep numarası gösterilir.
  • Sohbet sırasında temsilcinin adı, temsilci katıldığında bir bildirim (başka bir temsilciye aktarımdan sonra da), yazıyor göstergesi ve sohbeti sonlandırma düğmesi gösterilir. Mesajlar yalnızca düz metin içerir; en fazla 2.000 karakter olabilir ve bağlantı içermez. Henüz sunucuya ulaşmamış mesaj "Gönderiliyor..." olarak işaretlenir. Gönderim birkaç kez başarısız olursa yeniden denemek için mesaja dokunulabilir. Yeniden deneme, yinelenen 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 kademeli olarak artar. 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 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 bildirim yoktur. Mesajlar yalnızca uygulama açıkken gelir. Uygulama arka plandayken gönderilen bir yanıt, uygulamaya dönüldüğünde hemen görünür.
  • Sohbete erişim bilgileri bellekte tutulur. Cihazda ise yalnızca Android Keystore anahtarıyla şifrelenmiş olarak saklanır. URL'ye veya günlüklere yazılmaz. Sohbet sona erdiğinde, destek talebine dönüştüğünde, süresi dolduğunda veya setUser ile kullanıcı değiştirildiğinde bu bilgiler silinir.

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

Sorular, koşullar ve potansiyel müşteriler

Uygulamada 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 mesajla karşılık verir ve alan işaretlenir. Atlanabilen 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 onay metnini, ardından da onay mesajını gösterir. Potansiyel müşteri kaydı cihazda kuyruğa alınır ve sunucuya gönderilir. Ağ 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ı yok sayar.
  • Önceden doldurma: Destek talebi formu ve temsilciyle görüşme talep 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.
  • Geçerli ekran: Koşullar, geçerli ekranı kontrol edebilir. Kavchat.controller.livePage değerini ayarlayın (örneğin "checkout").

Toplanan değerler kişisel bilgidir. Cihazda kayıtlı sohbette tutulur ve yalnızca potansiyel müşteri kayıtlarına, destek taleplerine ve temsilciyle sohbetlere gönderilir; hiçbir zaman raporlara gönderilmez.

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

Son sürüm, ETag değeriyle birlikte SharedPreferences içinde saklanır ve her açılışta If-None-Match (304) ile yeniden kontrol edilir. Ağ bağlantısı yoksa kayıtlı 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 tükenmişse hiçbir şey gösterilmez. Açık bir sohbet, 30 dakika boyunca işlem yapılmayana kadar saklanır. Böylece sohbetten veya uygulamadan çıkmak, sohbeti baştan başlatmaz. Sohbet akışı, son işlemden iki saniye sonra ve uygulama arka plana geçtiğinde hemen raporlanır.