React Native

@kavchat/react-native paketi, uygulamanıza senaryo tabanlı destek sohbeti ekler: bir Provider, sohbet ekranı ve isteğe bağlı yüzen düğme. Yanıtlar, kontrol panelinde yayımladığınız senaryolardan gelir; senaryolar cihazda çalışır.

Kurulum

Paket tamamen JavaScript ile yazılmıştır; kendine ait yerel kodu veya simge kütüphanesi yoktur. Bu nedenle standart bir React Native uygulamasında ve Expo'da aynı şekilde çalışır. Eş bağımlılıklar: react 18 ve üzeri, react-native 0.72 ve üzeri.

React Native CLI (Expo olmadan)

yarn add @kavchat/react-native @react-native-async-storage/async-storage
cd ios && pod install

AsyncStorage yerel bir modüldür: iOS'ta pod install ile bağlanır, Android'de ise otomatik bağlanır.

Expo

Expo Go'da ve geliştirme derlemelerinde çalışır:

yarn add @kavchat/react-native
npx expo install @react-native-async-storage/async-storage

AsyncStorage olmadan

AsyncStorage, yayımlanan sürümü ve konuşmayı uygulama açılışları arasında saklar. Kurulması zorunlu değildir: kurulu değilse paket her şeyi bellekte tutar. Bot çalışmaya devam eder, ancak her açılışta sürümü yeniden indirir. MMKV gibi başka bir depolama çözümü kullanmak için storage özelliğine senkron veya asenkron herhangi bir { getItem, setItem, removeItem? } nesnesi iletin:

import { MMKV } from 'react-native-mmkv';
const mmkv = new MMKV();
const storage = {
  getItem: (k: string) => mmkv.getString(k) ?? null,
  setItem: (k: string, v: string) => mmkv.set(k, v),
  removeItem: (k: string) => mmkv.delete(k),
};

<KavchatProvider publicKey="pk_live_..." storage={storage}>

Kullanım

import { KavchatProvider, KavchatChat, KavchatLauncher, useKavchat } from '@kavchat/react-native';

export default function App() {
  return (
    <KavchatProvider publicKey="pk_live_..." onScreen={(screen, id) => navigation.navigate(screen, { id })}>
      <Navigation />
      {/* floating button, bottom end corner; opens the chat in a modal */}
      <KavchatLauncher />
    </KavchatProvider>
  );
}

// or as a screen in your own navigator
function SupportScreen() {
  return <KavchatChat />;
}

// or your own button
function HelpButton() {
  const { available, open } = useKavchat();
  if (!available) return null; // bot is off, limited to testers, or over quota
  return <Button title="Help" onPress={open} />;
}

KavchatProvider özellikleri

useKavchat(), { status, available, offline, locale, isOpen, open, close, toggle, setUser, startNewConversation, openContactForm, controller } döndürür.

KavchatChat özellikleri: onClose? (kapatma düğmesi gösterir), hideHeader? ve style?. KavchatLauncher özellikleri: style? (konum), onPress? (yerleşik pencere yerine kendi ekranınızı açmak için) ve attention? (false mesajı kapatır).

Yönetim ekranında sohbet düğmesinin yanında bir mesaj tanımlandığında (konuşma balonu veya düğmenin üzerinde kavisli metin), KavchatLauncher mesajı belirlenen gecikmeden sonra, günde en fazla bir kez gösterir. 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 açıkken mesaj yalnızca tabletlerde (ekranın kısa kenarı 600 puan veya üzerindeyse) gösterilir.

Kimlik belirteci

Belirteç yoksa kullanıcı misafir olarak kabul edilir ve iletişim formunda e-posta adresi veya telefon numarası istenir. Oturum açmış bir kullanıcıyı tanımlamak için gizli anahtarla kendi sunucunuzda kısa ömürlü bir JWT imzalayın (asla uygulamada imzalamayın; bkz. Kullanıcıları tanımlama) ve şöyle iletin:

<KavchatProvider publicKey="pk_live_..." userToken={session?.kavchatToken} userName={session?.firstName}>

userToken değiştiğinde (oturum açma veya kapatma) sürüm yeniden yüklenir; çünkü test kullanıcıları grubu, kullanıcının kimliğine bağlıdır. useKavchat().setUser({ token, name }) çağrısını da kullanabilirsiniz. Belirteç yalnızca Authorization: Bearer başlığında gönderilir ve cihazda saklanmaz. Kayıtlı konuşma, belirtecin parmak izine bağlıdır. Bu nedenle aynı cihazdaki başka bir kullanıcı yeni bir konuşma başlatır.

Bağlantılar, ekranlar ve iletişim formu

• link türündeki düğmeler yalnızca https: ve tel: adreslerini Linking.openURL aracılığıyla açar. Diğer adres türleri açılmaz.
• screen türündeki düğmeler onScreen işlevini çağırır. Sohbet kaldığı yerde kalır.
• "Ekibe ulaşın" düğmesi, konuşmanın eklendiği iletişim formunu açar. Gönderimden sonra talep numarası gösterilir.

Düzenleyicideki ekran listesi

Uygulamanın açabildiği ekranları, KavchatProvider bileşeninin screens özelliğinde bir kez tanımlayın. SDK listeyi kendisi Kavchat'e gönderir. Senaryo düzenleyicisi, serbest metin alanı yerine bu ekranları adlarıyla 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. Ekran listesini kontrol paneline elle girmek gerekmez.

const screens = [
  { id: 'orders', label: 'My orders' },
  { id: 'product', label: 'Product page', needsTarget: true }, // the button also carries a product id
];

<KavchatProvider
  publicKey="pk_live_..."
  screens={screens}
  onScreen={(screen, targetId) => navigation.navigate(screen, targetId ? { id: targetId } : undefined)}
>

• id, onScreen işlevine iletilen değerdir: Latin harfleri, rakamlar, _, . ve - içerebilir; en fazla 40 karakter olabilir. label, yöneticinin gördüğü addır; 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 ve 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 uyarı gösterilmez; bir sonraki açılışta yeniden denenir. Kullanıcı hiçbir şey görmez.
• Kaydedilen ekranlar, kontrol panelinde Bot, Ayarlar, "Uygulama ekranları" altında, her ekranı bildiren platformlarla birlikte görünür. Uygulamadan kaldırılan bir ekranı buradan silebilirsiniz.

Renkler ve RTL

Renkler, kontrol panelindeki bot ayarlarından (primaryColor) alınır. Bu rengin üzerindeki metin rengi, WCAG kontrastına göre seçilir. Şu renklerin her birini değiştirebilirsiniz: primary, background, botBubble, userBubble, text, muted, accent, onPrimary ve error:

<KavchatProvider
  publicKey="pk_live_..."
  theme={{ primary: '#0f766e', background: '#ffffff' }}
>

Paket, uygulamanın yerleşim yönünü değiştirmez. I18nManager.isRTL ayarına uyar (start ve end stilleri). Her metin kendi diline göre hizalanır; böylece İbranice ve Arapça, soldan sağa düzenlenmiş bir uygulamada da doğru okunur. Uygulamanız İbranice veya Arapçaysa her zamanki gibi uygulamada RTL'yi bir kez ayarlayın: I18nManager.forceRTL(true) ve ardından yeniden başlatma.

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

Temsilciyle canlı sohbet

Başlamak için herhangi bir ayar gerekmez. Yönetim ekranında temsilcilerle sohbeti açtığınızda, bu seçenek web sitesi bileşeninde olduğu gibi uygulamadaki sohbette de görünür.

• Seçenek: "Temsilciyle görüşün", "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 iletişim formu gösterilir. Formda 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: Misafirler, zamanında bir temsilci müsait olmazsa kendilerine ulaşılabilmesi için e-posta adresi veya telefon numarası bırakır. Ad ve ilk mesaj da eklenebilir. Birden fazla departman açıksa departman seçilir. Kimliği belirlenmiş kullanıcıların (userToken) iletişim bilgilerini doldurması gerekmez. Hiçbir temsilci sohbeti kabul edemiyorsa, önceden girilmiş bilgilerle iletişim formu açılır.
• Bekleme: "Temsilci bekleniyor" mesajı, belirlediğiniz bekleme süresinin sonuna kadar geri sayımla gösterilir. Yanında "Bunun yerine mesaj bırakın" ve "Sohbeti bitir" düğmeleri bulunur. Kullanıcı beklerken yazabilir. Süre dolduğunda sohbet otomatik olarak destek talebine dönüşür. Talep numarası ve zamanında hiçbir temsilcinin müsait olmadığına dair bir açıklama gösterilir.
• Sohbet: Temsilcinin adı, mesajlar, yazıyor göstergesi, başka bir temsilciye aktarma ve sohbeti sonlandırma. Sunucudan gelen her şey bağlantı içermeyen düz metin olarak gösterilir.
• Gerçek zamanlı iletişim: XMLHttpRequest üzerinden Server-Sent Events bağlantısı (desteklendiği yerlerde akışlı fetch). Bağlantı koparsa sohbet giderek artan aralıklarla yeniden bağlanır ve kaçırılan her şeyi tamamlar. Böylece hiçbir mesaj kaybolmaz veya iki kez gösterilmez. Bu bağlantıyı engelleyen ağlarda sohbet, tekrarlanan sorgulara (long-poll) geçer. Her mesajın bir kimliği vardır; bu nedenle yeniden denemek 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 bağlantı kapanır. Geri döndüğünde sohbet kaçırılanları tamamlar. Sohbet erişim belirteci en fazla 12 saat veya sohbet bitene kadar geçerlidir ve seçtiğiniz depolamada saklanır. Böylece uygulama yeniden başlatıldığında açık sohbet ekrana geri gelir. Belirteç URL'ye eklenmez ve günlüklere yazılmaz.
• Bu sürümde push bildirimi yoktur: Temsilcinin mesajları yalnızca uygulama açıkken gelir.

Erişim belirtecini güvenli depolamada saklamanızı öneririz (iOS'ta Keychain, Android'de Keystore). secureStorage tanımlanmazsa belirteç, konuşmayla aynı depolamada saklanır. Temsilciyle görüşmek için kendi düğmenizi kullanırsanız, müsait bir temsilci varken görüşme isteği formu açılır. Müsait temsilci yoksa açıklamayla birlikte iletişim formu açılır:

import * as SecureStore from 'expo-secure-store';

// expo-secure-store allows only [A-Za-z0-9._-] in keys
const safe = (k: string) => k.replace(/[^A-Za-z0-9._-]/g, '_');
const secureStorage = {
  getItem: (k: string) => SecureStore.getItemAsync(safe(k)),
  setItem: (k: string, v: string) => SecureStore.setItemAsync(safe(k), v),
  removeItem: (k: string) => SecureStore.deleteItemAsync(safe(k)),
};

<KavchatProvider publicKey="pk_live_..." secureStorage={secureStorage} livePage="checkout">

// your own button
const { openLive } = useKavchat();
<Button title="Chat with us" onPress={openLive} />

Olaylar: Sohbetin durumu her değiştiğinde onEvent, { type: 'live', phase } alır (queued, active, closed, ticket, replaced, expired).

Sorular, koşullar ve potansiyel müşteriler

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 bilgilerini gönderebilir. Her şey cihazda çalışır.

• Uygun klavye: Bot yanıt beklerken metin alanında otomatik tamamlamalı telefon, e-posta veya sayı klavyesi açılır. Yanıt geçersizse bot neyin eksik olduğunu açıklar ve alan işaretlenir. Atlanabilen sorularda "Atla" düğmesi görünür.
• Potansiyel müşteri: Onay metni varsa "Gönder" ve "Hayır, teşekkürler" düğmeleri görünür. Ağ bağlantısı yoksa potansiyel müşteri bilgileri cihazda saklanır ve bağlantı geri geldiğinde yinelenmeden gönderilir.
• Önceden doldurma: Kullanıcının verdiği yanıtlar, iletişim formunu ve temsilciyle görüşme isteği formunu doldurur; destek talebine ve temsilciyle yapılan sohbete eklenir. Kimlik belirtecindeki ad, e-posta ve telefon bilgileri bilinen yanıtlar olarak kabul edilir ve bot bunları tekrar sormaz.
• Geçerli ekran: livePage, koşulların kontrol ettiği ve potansiyel müşteri bilgileriyle birlikte gönderilen ekranı da belirtir. Özellik değiştirildiğinde bu bilgi güncellenir.

Yapay zekâ yanıtları (Premium)

Uygulamada ayar yapmanız gerekmez. Yönetim ekranında yapay zekâ yanıtlarını açtığınızda (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 konuya yönlendiren 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ıra ulaşırsa (her 15 dakikada konuşma başına 10 yanıt), sohbet standart "Yanıt bulamadım" mesajını gösterir. Soru, yanıtsız sorular raporunda yine yer alır. Yapay zekâ yanıtları da diğer mesajlar gibi kayıtlı konuşmada saklanır.

Çalışma biçimi

• Yayımlanan sürüm, ETag değeriyle birlikte önbelleğe alınır (If-None-Match, 304). Ağ bağlantısı yokken kayıtlı sürüm, bu durumu belirten bir mesajla gösterilir.
• Konuşma cihazda saklanır; sürüm ve kullanıcı 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 raporlanır.
• İstekler özel başlık göndermez; yalnızca Authorization, Content-Type ve If-None-Match gönderilir.