Android

ספריית ה-Android של Kavchat מוסיפה לאפליקציה את בוט השירות לפי תסריט, עם רכיבי Jetpack Compose ו-Activity לאפליקציות שבנויות עם Views. התשובות צפויות וממשיכות לעבוד גם בלי רשת, מהגרסה האחרונה שפורסמה. נדרשת Android 6.0 (API 23) ומעלה.

יש שני רכיבים: kavchat-engine, גרסת Kotlin/JVM של מנוע השיחה, בלי תלות ב-Android או בספריות צד שלישי, ו-kavchat, עם התקשורת (HttpURLConnection), המטמון במכשיר (SharedPreferences), רכיבי ה-Compose KavchatChat ו-KavchatLauncher, ו-KavchatActivity.

התקנה

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

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

הספרייה מוגשת דרך JitPack, ולכן מוסיפים פעם אחת את המאגר שלו, ליד google() ו-mavenCentral(). ה-SDK בקוד פתוח, ברישיון MIT: bitbucket.org/maxsave/kavchat-android.

הספרייה מצהירה בעצמה על ההרשאה INTERNET ועל KavchatActivity ב-manifest שלה. אין צורך להוסיף דבר ידנית.

הגדרה

קוראים ל-configure פעם אחת, ב-Application.onCreate:

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")
    }
}

מותר לכלול באפליקציה את המפתח הציבורי. את המפתח הסודי (sk_live_...) אסור לכלול בה אף פעם.

Compose

כפתור צף בפינה שנבחרה בלוח הבקרה, שפותח את הצ'אט במסך מלא:

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

אפשר גם למקם את הכפתור בעצמכם, או להטמיע את הצ'אט במסך משלכם:

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

פותחים וסוגרים את הצ'אט של הכפתור הצף מהקוד עם Kavchat.controller.setPresented(true) ו-setPresented(false).

Views (בלי Compose באפליקציה)

Kavchat.open(context)                                // starts KavchatActivity

מ-Java: Kavchat.open(context);. ה-Activity משתמשת ב-Compose בתוכה, אבל האפליקציה שלכם לא צריכה.

טוקן זהות

מזהים משתמש מחובר עם JWT שהשרת שלכם חותם במפתח הסודי (ראו זיהוי משתמשים). הטוקן נשלח בכותרת Authorization: Bearer <token>. משתמש מזוהה יכול לראות גרסאות שפתוחות רק לבודקים, ולשלוח את טופס הפנייה בלי מייל או טלפון.

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

החלפת משתמש טוענת מחדש את הגרסה ומתחילה שיחה חדשה, כך שהשיחה של משתמש אחד לא מופיעה אצל אחר.

מסכים באפליקציה: onScreen

כפתור מסוג screen בתסריט מבקש מהאפליקציה לפתוח אחד המסכים שלה. הצ'אט נסגר קודם (הדיאלוג של KavchatLauncher או KavchatActivity), כדי שהמסך ייראה:

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

בלי handler הכפתורים האלה לא עושים כלום. כפתורי link פותחים רק קישורי https (בדפדפן) ו-tel (בחייגן). לניתוח נתונים, Kavchat.onEvent מדווח על Ready, Unavailable, Open, Close, Effect ו-Ticket.

רשימת המסכים בעורך

מצהירים פעם אחת על המסכים שהאפליקציה יודעת לפתוח ב-Kavchat.configure(..., screens = ...) (הטיפוס KavchatAppScreen). ערכת הפיתוח שולחת את הרשימה ל-Kavchat בעצמה, ועורך התסריטים מציע את המסכים האלה ברשימה נפתחת עם השמות שלהם, במקום שדה טקסט חופשי. העורך גם מבקש מזהה פריט כשמסך צריך אותו, ומזהיר על כפתור שמוביל למסך שלא הוצהר. אף אחד לא מקליד את רשימת המסכים ידנית בלוח הבקרה.

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: אותיות לטיניות, ספרות, _, . ו--, עד 40 תווים. label הוא השם שהמנהל רואה, עד 60 תווים. עד 100 מסכים. רשומות לא תקינות ומזהים כפולים מושמטים.
• needsTarget: הכפתור נושא גם מזהה פריט (למשל מזהה מוצר), והוא מגיע ל-onScreen בתור targetId.
• הרשימה נשלחת ברקע אחרי שהגרסה נטענת, רק כשהיא השתנתה או פעם בשבוע. כישלון לא מורגש, והשליחה תנוסה שוב בהפעלה הבאה. המשתמש לא רואה כלום.
• המסכים שנרשמו מופיעים בלוח הבקרה תחת בוט, הגדרות, "מסכי האפליקציה", עם הפלטפורמות שדיווחו על כל מסך. מסך שהוסר מהאפליקציה אפשר למחוק שם.

צבעים

הצבעים מגיעים מלוח הבקרה (primaryColor). הטקסט על צבע המותג לבן או כמעט שחור לפי ניגודיות WCAG, וצבע בהיר מדי לטקסט על רקע לבן מוחלף בכמעט שחור בקישורים ובכפתורים. גם שם הבוט, כותרת המשנה, התמונה והצד של הכפתור הצף (start או end) מגיעים מלוח הבקרה, ולכן משתנים בלי לעדכן את האפליקציה. המשטחים והטיפוגרפיה לוקחים את ה-MaterialTheme שלכם.

התג "מופעל על ידי Kavchat by maxsave" מוצג בכל החבילות, עם קישור ל-kavchat.com. בפרימיום אפשר להסתיר אותו בהגדרות הבוט.

שפות ו-RTL

• שפת הממשק היא ה-locale שהועבר ל-configure. אם לא הועבר, שפת המכשיר אם יש לה תרגום (he, en, ar, ru, es, fr, de, pt, it, tr), אחר כך שפת התסריט, ובסוף אנגלית.
• ההתאמה לתסריט נעשית תמיד בשפת התסריט (מילים נפוצות שמדלגים עליהן, ותחיליות בעברית ובערבית).
• בעברית ובערבית ה-LocalLayoutDirection של כל הצ'אט הוא RTL. שום דבר לא הפוך ידנית: אם אתם עוטפים את הרכיבים, השתמשו ב-start וב-end. השאירו android:supportsRtl="true" ב-manifest של האפליקציה.

תשובות AI (פרימיום)

אין מה להגדיר באפליקציה. כשמפעילים תשובות AI במסך הניהול (עם מפתח של ספק AI משלכם), שאלה שאף תסריט לא עונה עליה נשלחת ל-Kavchat, ובזמן ההמתנה, עד 20 שניות, הצ'אט מראה שהבוט מקליד. התשובה מוצגת כטקסט רגיל עם תווית קטנה "תשובת AI" בשפת הממשק, ומתחתיה כפתור לנושא קשור, אם יש כזה, וכפתור "פנייה לצוות".

אם אין תשובה, או שהבקשה נכשלה, לקחה יותר מדי זמן או עברה את המגבלה (10 תשובות לשיחה בכל 15 דקות), הצ'אט מציג את ההודעה הרגילה של "לא מצאתי תשובה". השאלה עדיין מופיעה בדוח השאלות שלא נמצאה להן תשובה, ותשובות AI נשמרות בשיחה השמורה כמו כל הודעה אחרת.

צ'אט עם נציג

אין צורך להגדיר שום דבר באפליקציה. כשמפעילים צ'אט עם נציגים במסך הניהול, הצ'אט באפליקציה פועל בדיוק כמו הווידג'ט באתר.

• האפשרות מוצגת רק כשהצ'אט עם נציגים מופעל בגרסה שפורסמה. כשהבוט מציג "פנייה לצוות", ה-SDK בודק אם יש נציג פנוי. התשובה נשמרת ל-30 שניות. אם יש נציג פנוי, מופיע לפניו כפתור "שיחה עם נציג". אם אין, מוצג רק טופס הפנייה. מעליו מופיעה שורה קצרה שמסבירה למה: מחוץ לשעות הפעילות (כולל השעה שבה חוזרים) או שכל הנציגים עסוקים.
• לפני השיחה ממלאים טופס קצר: שם, אימייל או טלפון, מחלקה (רק כשיש יותר ממחלקה פתוחה אחת) והודעה ראשונה (לא חובה). אורח חייב להשאיר אימייל או טלפון. משתמש שזוהה באמצעות טוקן זהות לא נדרש להשאיר אף אחד מהם. אם בזמן השליחה כבר אין נציג פנוי, נפתח טופס הפנייה עם הפרטים שכבר מולאו.
• בזמן ההמתנה מוצגים הזמן שנותר עד שהשיחה תהפוך לפנייה וכפתור "להשאיר הודעה במקום". זמן ההמתנה נקבע במסך הניהול, וברירת המחדל היא 2 דקות. אפשר לכתוב גם בזמן ההמתנה, והנציג יראה את ההודעות. אם אף נציג לא מתפנה בזמן, השיחה נשמרת כפנייה רגילה ומוצג מספר הפנייה.
• במהלך השיחה מוצגים שם הנציג, הודעה כשנציג מצטרף (גם אחרי העברה לנציג אחר), סימן כשהנציג מקליד וכפתור לסיום השיחה. ההודעות כוללות טקסט פשוט בלבד, עד 2000 תווים, בלי קישורים. הודעה שעדיין לא הגיעה לשרת מסומנת "שולח...". אם השליחה נכשלה כמה פעמים, אפשר להקיש על ההודעה כדי לנסות שוב. ניסיון חוזר לא יוצר הודעה כפולה.
• אחרי כל ניתוק ה-SDK ממתין מעט, משלים את מה שהוחמץ ומתחבר מחדש. זמן ההמתנה גדל בהדרגה. ההודעות תמיד מוצגות לפי הסדר ובלי כפילויות. אם החיבור הרציף לא מצליח (למשל מאחורי פרוקסי ארגוני), ה-SDK עובר זמנית לבדיקות חוזרות מול השרת.
• כשהאפליקציה עוברת לרקע, החיבור נסגר. כשחוזרים לאפליקציה, ה-SDK משלים את מה שהוחמץ ומתחבר מחדש. שיחה פתוחה ממשיכה גם אחרי סגירה והפעלה מחדש של האפליקציה, כל עוד לא עברו 12 שעות.
• בגרסה הזו אין התראות פוש. הודעות מגיעות רק כשהאפליקציה פתוחה. תשובה שנשלחה כשהאפליקציה ברקע מופיעה מיד כשחוזרים אליה.
• פרטי הגישה לשיחה נשמרים בזיכרון. במכשיר הם נשמרים רק כשהם מוצפנים במפתח של Android Keystore. הם לא נכתבים בכתובת או ביומן. הפרטים נמחקים כשהשיחה מסתיימת, הופכת לפנייה או פג תוקפה, וגם כשמחליפים משתמש ב-setUser.

אפשר להשתמש ב-Kavchat.controller.livePage כדי לציין לנציג מאיזה מסך הגיע המשתמש.

שאלות, תנאים ולידים

אין צורך בהגדרות באפליקציה. תסריט יכול לבקש פרטים (שם, טלפון, אימייל, מספר או טקסט חופשי), לבחור איך להמשיך לפי המידע הידוע ולשלוח ליד.

• מקלדת מתאימה: כשהבוט מחכה לתשובה, בשדה הטקסט מוצגת מקלדת טלפון, אימייל או מספרים. בשאלת שם, המקלדת עוברת לאותיות גדולות בתחילת מילה. אם התשובה לא תקינה, הבוט מגיב בהודעה קצרה בשפת הצ'אט והשדה מסומן. בשאלה שאפשר לדלג עליה מופיע כפתור "דילוג". "ביטול", בכל שפה נתמכת, מוציא מהשאלה.
• טלפון: למספר בלי + משויכת מדינת ברירת המחדל של סביבת העבודה (בהגדרות במסך הניהול).
• ליד: שלב ליד מציג את שורת ההסכמה עם הכפתורים "שליחה" ו"לא, תודה", ואחר כך את הודעת האישור. הליד נכנס לתור במכשיר ונשלח לשרת. כשאין חיבור לרשת או כשהשרת לא זמין, מתבצעים ניסיונות שליחה חוזרים (גם בהפעלה הבאה ואחרי reload()). השרת מתעלם מכפילויות.
• מילוי מראש: טופס הפנייה וטופס הבקשה לנציג מתמלאים בשם, באימייל ובטלפון שנאספו. כל הערכים שנאספו מצורפים לפנייה או לבקשה לנציג. שאלות לפני שיחה עם נציג (פרימיום) נשאלות לפני החיבור.
• טוקן זהות: בשימוש ב-setUser, השדות name, email ו-phone שבטוקן ממלאים את התשובות לשאלות המתאימות, והבוט מדלג עליהן.
• המסך הנוכחי: תנאים יכולים לבדוק את המסך הנוכחי. מגדירים Kavchat.controller.livePage (למשל "checkout").

הערכים שנאספים הם מידע אישי. הם נשארים בשיחה השמורה במכשיר ונשלחים רק ללידים, לפניות ולשיחות עם נציג, ולעולם לא לדוחות.

עבודה בלי רשת ומטמון

הגרסה האחרונה נשמרת ב-SharedPreferences עם ה-ETag שלה, ונבדקת מחדש עם If-None-Match (304) בכל הפעלה. כשאין רשת נעשה שימוש בעותק השמור ומוצגת הודעה על כך. כשהבוט כבוי, פתוח רק לבודקים או שנגמרה המכסה, שום דבר לא מוצג. שיחה פתוחה נשמרת עד 30 דקות בלי פעילות, כך שיציאה מהצ'אט או מהאפליקציה לא מתחילה אותה מחדש. מהלך השיחה מדווח שתי שניות אחרי הפעולה האחרונה, ומיד כשהאפליקציה עוברת לרקע.