Kavchat by maxsave
Rehber menüsü

Flutter

kavchat_flutter paketi, Flutter uygulamanıza senaryo tabanlı destek sohbeti ekler: düğmeler, serbest metin eşleştirme, destek talebi açan bir form, botun çevrimdışı da çalışan bir kopyası ve İbranice ile Arapça için sağdan sola görünüm.

Kurulum

pubspec.yaml
dependencies:
  kavchat_flutter: ^0.0.11

Paket; http, shared_preferences (sürüm önbelleği ve kayıtlı konuşma) ve url_launcher (senaryolardaki bağlantılar) bağımlılıklarını içerir. Android 11 ve üzeri sürümlerde tel: bağlantılarını açmak için AndroidManifest.xml dosyasına tel şeması için bir <queries> kaydı, web bağlantıları için de bir https kaydı ekleyin (url_launcher README dosyasına bakın). iOS'ta LSApplicationQueriesSchemes yalnızca canLaunchUrl işlevini kendiniz çağırıyorsanız gereklidir.

Kullanım

Dart
final kavchat = KavchatController(
  publicKey: 'pk_live_...',
  // apiBase: 'https://api.kavchat.com', // default
  // locale: 'he',                        // default: device language if translated, else the bot language
  onScreen: (screen, targetId) => navigatorKey.currentState?.pushNamed('/$screen', arguments: targetId),
);

Scaffold(
  floatingActionButton: KavchatLauncher(controller: kavchat), // hidden while the bot is off
);

// or open it yourself
showKavchat(context, kavchat);

// or embed the screen in your own route
KavchatChat(controller: kavchat, onClose: () => Navigator.pop(context));

Denetleyiciyi bir kez oluşturun (örneğin State veya bir provider içinde) ve onu barındıran nesneyle birlikte dispose() çağrısını yapın.

KavchatLauncher bir FloatingActionButton bileşenidir. Konumunu Scaffold.floatingActionButtonLocation ile belirleyin. kavchat.settings?.position ayarı (start veya end), yönetim panelinde hangi tarafın seçildiğini belirtir.

Yönetim panelinde sohbet düğmesinin yanında bir mesaj tanımlandığında (konuşma balonu, düğmenin üzerinde kavisli metin, kapsül şeklinde genişleyip konuşan düğme veya düğmeden yukarı uzanıp botun ilk seçeneklerini gösteren bir çizgi), KavchatLauncher bu mesajı belirlenen gecikmenin ardından günde en fazla bir kez gösterir. Çizgideki bir seçeneğe dokunulduğunda, sohbet o seçenek içeride seçilmiş gibi açılır. Mesajı kapatmak veya sohbeti açmak, mesajı ertesi güne kadar gizler. Sohbet açıkken mesaj gösterilmez. Cihazda hareketi azaltma ayarı açıksa mesaj hareketsiz gösterilir. "Telefonlarda gösterme" seçeneği etkinse mesaj yalnızca tabletlerde gösterilir (ekranın kısa kenarı 600 nokta veya üzerindeyse). Telefonda çizgi en fazla iki seçenek gösterir. KavchatLauncher(controller: kavchat, attention: false) mesajın gösterilmesini devre dışı bırakır.

Temadaki düğme simgesi bir yüz olduğunda, düğme boşta dururken yüz ara sıra göz kırpar. Sohbet açıkken, uygulama arka plandayken veya hareketi azaltma ayarı açıkken göz kırpmaz.

Sürümde enabled: false olduğunda bot gösterilmez (yüzen düğme görünmez ve KavchatChat "Kullanılamıyor" mesajını gösterir): bot kapalıdır, yalnızca test kullanıcılarına açıktır ve kullanıcı bu grupta değildir veya kota tükenmiştir (reason: 'quota').

Kimlik belirteci

Oturum açmış kullanıcılar için gizli anahtarla kendi sunucunuzda kısa bir JWT imzalayın (asla uygulama içinde değil, bkz. Kullanıcıları tanımlama) ve iletin:

Dart
KavchatController(publicKey: 'pk_live_...', userToken: jwt, userName: 'Dana');
await kavchat.setUser(token: newJwt, name: 'Dana'); // after login
await kavchat.setUser(token: null);                 // after logout

Belirteç, her çağrıda Authorization: Bearer <token> başlığında gönderilir. Belirteç varsa destek talebi formunda e-posta veya telefon zorunlu değildir ve kullanıcı test kullanıcıları grubunda tanınır. setUser sürümü yeniden yükler. Farklı bir kullanıcı için yeni bir konuşma başlatılır; böylece cihazda kayıtlı bir konuşma hiçbir zaman başka bir hesaba aktarılmaz.

Bağlantılar, ekranlar ve destek talebi formu

  • link türündeki düğmeler, url_launcher ile yalnızca https: ve tel: adreslerini açar. Bot mesajlarındaki bağlantılar yalnızca https: olabilir.
  • screen türündeki düğmeler onScreen(screen, targetId) işlevini çağırır. Bu işlev yoksa hiçbir şey yapmazlar.
  • "Ekibe ulaşın" düğmesi, yerleşik formu açar (ad, e-posta, telefon, konu ve mesaj; konuşma da eklenir). Gönderimin ardından destek talebi numarasını gösterir.

Düzenleyicideki ekran listesi

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

Dart
final kavchat = KavchatController(
  publicKey: 'pk_live_...',
  screens: const [
    KavchatScreen(id: 'orders', label: 'My orders'),
    KavchatScreen(id: 'product', label: 'Product page', needsTarget: true), // the button carries a targetId
  ],
  onScreen: (screen, targetId) => navigatorKey.currentState?.pushNamed('/$screen', arguments: targetId),
);
// later, to replace the list: await kavchat.registerScreens([...]);
  • id, onScreen işlevine iletilen değerdir: Latin harfleri, rakamlar, _, . ve - içerebilir; 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 değer, 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.

RTL

Sohbet, kendi Directionality değerini arayüz diline göre belirler: he ve ar için sağdan sola, diğer tüm diller için soldan sağa. Uygulamanızın yönünü değiştirmez. Her balon da yönünü, yönü belirgin ilk harfe göre seçer; böylece farklı yazı yönlerini bir arada içeren metinler doğru okunur. Arayüz dili ile senaryo dili birbirinden bağımsızdır: İngilizce bir bot, locale: 'ar' olduğunda "Geri" gibi düğmeleri Arapça gösterebilir.

Renkler ve markalama

Renkler, botun primaryColor ayarından alınır. Bu rengin üzerindeki metin, WCAG kontrastına göre siyah veya beyaz olur. Renk çok açıksa metin rengi olarak kullanıldığı yerlerde koyu bir renkle değiştirilir. Renkleri şöyle değiştirebilirsiniz:

Dart
KavchatLauncher(controller: kavchat, theme: KavchatThemeData.fromColor(const Color(0xFF0F766E)));
KavchatChat(controller: kavchat, theme: KavchatThemeData.fromHex('#0f766e').copyWith(background: Colors.white));

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

Temsilciyle canlı sohbet

Başlamak için herhangi bir ayar yapmanız gerekmez. Yönetim panelinde temsilciyle sohbeti etkinleştirdiğinizde, bu seçenek web sitesi bileşeninde olduğu gibi uygulamanızdaki sohbette de görünür.

  • Seçenek: "Temsilciyle görüşme", "Ekibe ulaşın" seçeneğinden önce ve yalnızca sunucu müsait bir temsilci olduğunu doğruladıktan sonra görünür. Düğmeye dokunulduğunda müsaitlik yeniden kontrol edilir. Ç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 tükendiğinde form açıklama olmadan gösterilir.
  • Görüşme talebi: Ziyaretçiler, zamanında müsait bir temsilci bulunamaması ihtimaline karşı e-posta veya telefon bırakır. Ad ve ilk mesaj da eklenebilir. Birden fazla departman açıksa departman seçilir. Kimliği doğrulanmış kullanıcıların (userToken) iletişim bilgilerini doldurması gerekmez. Hiçbir temsilci görüşmeyi alamazsa, girilmiş bilgilerle birlikte destek talebi formu açılır.
  • Bekleme: Belirlediğiniz bekleme süresinin sonuna kadar geri sayımla birlikte "Temsilci bekleniyor" mesajı ve yanında "Bunun yerine mesaj bırakma" ile "Görüşmeyi bitirme" düğmeleri gösterilir. Beklerken de mesaj yazılabilir. Süre dolduğunda görüşme otomatik olarak destek talebine dönüşür. Destek talebi numarası ve zamanında müsait bir temsilci bulunamadığını belirten bir açıklama gösterilir.
  • Görüşme: Temsilcinin adı, mesajlar, yazıyor göstergesi, başka bir temsilciye aktarma ve görüşmeyi bitirme. Sunucudan gelen her şey bağlantı içermeyen düz metin olarak gösterilir.
  • Gerçek zamanlı iletişim: Akış halinde gelen bir http yanıtı üzerinden Server-Sent Events bağlantısı kullanılır. Bağlantı koparsa sohbet, giderek uzayan aralıklarla yeniden bağlanır ve kaçırılan her şeyi tamamlar. Böylece hiçbir mesaj kaybolmaz veya iki kez görünmez. Bu bağlantıyı engelleyen ağlarda ve Flutter Web'de sohbet, tekrarlanan sorgularla (long-poll) çalışır. 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.
  • Arka plana geçiş ve yeniden başlatma: Uygulama arka plana geçtiğinde (paused, hidden) bağlantı kapatılır. Uygulama geri döndüğünde (resumed) sohbet, kaçırılanları tamamlar. Görüşme erişim bilgisi en fazla 12 saat veya görüşme bitene kadar geçerlidir ve seçtiğiniz depolama alanında saklanır. Böylece uygulama yeniden başlatıldığında açık görüşme ekrana geri gelir. Erişim bilgisi adreste saklanmaz ve günlüklere yazılmaz.
  • Bu sürümde anlık bildirim yoktur: Temsilcinin mesajları yalnızca uygulama açıkken gelir.

Erişim bilgisini güvenli depolamada (iOS'ta Keychain, Android'de Keystore), örneğin flutter_secure_storage ile saklamanız önerilir. secureStorage tanımlamazsanız erişim bilgisi, konuşmayla aynı depolama alanında saklanır. Temsilciyle görüşmek için eklediğiniz kendi düğmeniz, müsait bir temsilci varsa görüşme talebi formunu açar. Müsait temsilci yoksa açıklamayla birlikte destek talebi formu açılır:

Dart
import 'package:flutter_secure_storage/flutter_secure_storage.dart';

class SecureKavchatStorage implements KavchatStorage {
  final _s = const FlutterSecureStorage();
  @override
  Future<String?> read(String key) => _s.read(key: key);
  @override
  Future<void> write(String key, String value) => _s.write(key: key, value: value);
  @override
  Future<void> remove(String key) => _s.delete(key: key);
}

final kavchat = KavchatController(
  publicKey: 'pk_live_...',
  secureStorage: SecureKavchatStorage(),
  livePage: 'checkout',
  onLivePhase: (phase) => debugPrint('live chat: $phase'),
);

// your own button
FilledButton(onPressed: kavchat.openLive, child: const Text('Chat with us'));

Aynı mantık, Flutter olmadan kavchat_engine içinde bulunur (KavchatClient, LiveSession ve web sitesi bileşeniyle aynı test vektörlerini geçen ortak durum makinesi liveApplyEvent, liveLines ve liveStatus).

Sorular, koşullar ve potansiyel müşteri kayıtları

Uygulamada ayar yapmanız gerekmez. Bir senaryo bilgi isteyebilir (ad, telefon, e-posta, sayı veya metin), koşullara göre nasıl devam edeceğini seçebilir (Premium) ve potansiyel müşteri kaydı gönderebilir. Her şey cihazda çalışır.

  • Uygun klavye: Bot yanıt beklerken metin alanında otomatik tamamlama destekli telefon, e-posta veya sayısal klavye açılır. Yanıt geçersizse bot neyin eksik olduğunu açıklar ve alan işaretlenir. Atlanabilen sorularda "Atlama" düğmesi görünür.
  • Potansiyel müşteri kaydı: Onay metni varsa "Gönderme" ve "Hayır, teşekkürler" düğmeleri görünür. İnternet bağlantısı yoksa kayıt cihazda saklanır ve bağlantı geri geldiğinde yinelenmeden gönderilir.
  • Önceden doldurma: Kullanıcının daha önce verdiği yanıtlar, destek talebi formunu ve temsilciyle görüşme talebi formunu doldurur; destek talebine ve temsilciyle görüşmeye eklenir. Kimlik belirtecindeki ad, e-posta ve telefon bilinen yanıtlar olarak kabul edilir; bot bunları tekrar sormaz.
  • Mevcut ekran: livePage, koşulların kontrol ettiği ve potansiyel müşteri kayıtlarıyla gönderilen ekranı da belirtir. Kullanıcı başka bir ekrana geçtiğinde setPage('checkout') çağrısını yapın.

Yapay zekâ yanıtları (Premium)

Uygulamada 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ığı 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 bulunur.

Yanıt yoksa veya istek başarısız olmuşsa, çok uzun sürmüşse ya da sınır aşılmışsa (her 15 dakikada konuşma başına 10 yanıt), sohbet normal "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ı konuşmada saklanır.

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

Sürüm, ETag değeriyle birlikte önbelleğe alınır (If-None-Match, 304). İnternet bağlantısı olmadığında veya sunucu hatası oluştuğunda kayıtlı kopya kullanılır ve bunu belirten bir mesaj gösterilir. Konuşma her bot için ayrı saklanır ve sürüm değişmediği sürece 24 saat boyunca geri yüklenir. Konuşmanın akışı, son işlemden 2 saniye sonra ve uygulama arka plana geçtiğinde sunucuya bildirilir.