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 จึงต้องเพิ่มรีโพซิทอรีของ 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) SDK จะส่งรายการไปยัง 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 สำหรับ Premium สามารถซ่อนป้ายนี้ได้ในการตั้งค่าบอท

ภาษาและ RTL

• ภาษาอินเทอร์เฟซจะใช้ locale ที่ส่งให้ configure หากไม่ได้ส่ง จะใช้ภาษาของอุปกรณ์ถ้ามีคำแปล (he, en, ar, ru, es, fr, de, pt, it, tr) ถ้าไม่มีจะใช้ภาษาของสคริปต์ และสุดท้ายคือภาษาอังกฤษ
• การจับคู่กับสคริปต์จะใช้ภาษาของสคริปต์เสมอ (คำที่พบบ่อยซึ่งจะข้ามไป และคำเติมหน้าในภาษาฮีบรูและอาหรับ)
• ในภาษาฮีบรูและอาหรับ LocalLayoutDirection ของแชททั้งหมดจะเป็น RTL ไม่มีการกลับด้านด้วยตนเอง หากครอบคอมโพเนนต์ด้วยองค์ประกอบอื่น ให้ใช้ start และ end และคง android:supportsRtl="true" ไว้ใน manifest ของแอป

คำตอบจาก AI (Premium)

ไม่ต้องตั้งค่าอะไรในแอป เมื่อเปิดใช้คำตอบจาก AI ในหน้าจัดการ (ด้วยคีย์ของผู้ให้บริการ AI ของคุณเอง) คำถามที่ไม่มีสคริปต์ใดตอบได้จะถูกส่งไปยัง Kavchat ระหว่างรอสูงสุด 20 วินาที แชทจะแสดงว่าบอทกำลังพิมพ์ คำตอบจะแสดงเป็นข้อความธรรมดาพร้อมป้ายเล็ก ๆ ว่า "คำตอบจาก AI" ในภาษาอินเทอร์เฟซ ด้านล่างมีปุ่มหัวข้อที่เกี่ยวข้องหากมี และปุ่ม "ติดต่อทีมงาน"

หากไม่มีคำตอบ หรือคำขอล้มเหลว ใช้เวลานานเกินไป หรือเกินขีดจำกัด (10 คำตอบต่อบทสนทนาในทุก 15 นาที) แชทจะแสดงข้อความ "ไม่พบคำตอบ" ตามปกติ คำถามยังคงปรากฏในรายงานคำถามที่ไม่มีคำตอบ และคำตอบจาก AI จะถูกเก็บไว้ในบทสนทนาที่บันทึกไว้เช่นเดียวกับข้อความอื่น

แชทกับเจ้าหน้าที่

ไม่ต้องตั้งค่าอะไรในแอป เมื่อเปิดใช้แชทกับเจ้าหน้าที่ในหน้าจัดการ แชทในแอปจะทำงานเหมือนวิดเจ็ตบนเว็บไซต์ทุกประการ

• ตัวเลือกนี้จะแสดงเฉพาะเมื่อเปิดใช้แชทกับเจ้าหน้าที่ในเวอร์ชันที่เผยแพร่ เมื่อบอทแสดง "ติดต่อทีมงาน" SDK จะตรวจสอบว่ามีเจ้าหน้าที่ว่างหรือไม่ และเก็บผลไว้ 30 วินาที หากมีเจ้าหน้าที่ว่าง ปุ่ม "คุยกับเจ้าหน้าที่" จะแสดงก่อนปุ่มนั้น หากไม่มี จะแสดงเฉพาะแบบฟอร์มติดต่อ พร้อมข้อความสั้น ๆ ด้านบนอธิบายเหตุผลว่าอยู่นอกเวลาทำการ (รวมเวลาที่กลับมาให้บริการ) หรือเจ้าหน้าที่ทุกคนกำลังให้บริการอยู่
• ก่อนเริ่มแชท ให้กรอกแบบฟอร์มสั้น ๆ ได้แก่ ชื่อ อีเมลหรือเบอร์โทรศัพท์ แผนก (เฉพาะเมื่อมีแผนกเปิดให้บริการมากกว่าหนึ่งแผนก) และข้อความแรก (ไม่บังคับ) ผู้ใช้ทั่วไปต้องระบุอีเมลหรือเบอร์โทรศัพท์ ส่วนผู้ใช้ที่ระบุตัวตนด้วยโทเค็นยืนยันตัวตนไม่จำเป็นต้องระบุทั้งสองอย่าง หากไม่มีเจ้าหน้าที่ว่างแล้วในขณะที่ส่ง แบบฟอร์มติดต่อจะเปิดขึ้นพร้อมข้อมูลที่กรอกไว้
• ระหว่างรอ จะแสดงเวลาที่เหลือก่อนที่แชทจะเปลี่ยนเป็นคำร้อง และปุ่ม "ฝากข้อความแทน" เวลารอกำหนดได้ในหน้าจัดการ โดยค่าเริ่มต้นคือ 2 นาที สามารถพิมพ์ข้อความระหว่างรอได้ และเจ้าหน้าที่จะเห็นข้อความเหล่านั้น หากไม่มีเจ้าหน้าที่ว่างภายในเวลาที่กำหนด บทสนทนาจะถูกบันทึกเป็นคำร้องปกติและแสดงหมายเลขคำร้อง
• ระหว่างแชท จะแสดงชื่อเจ้าหน้าที่ ข้อความเมื่อเจ้าหน้าที่เข้าร่วม (รวมถึงหลังโอนไปยังเจ้าหน้าที่คนอื่น) สัญลักษณ์เมื่อเจ้าหน้าที่กำลังพิมพ์ และปุ่มจบการสนทนา ข้อความรองรับเฉพาะข้อความธรรมดาไม่เกิน 2,000 ตัวอักษร ไม่มีลิงก์ ข้อความที่ยังไม่ถึงเซิร์ฟเวอร์จะแสดงว่า "กำลังส่ง..." หากส่งไม่สำเร็จหลายครั้ง สามารถแตะข้อความเพื่อลองอีกครั้งได้ การลองใหม่จะไม่สร้างข้อความซ้ำ
• ทุกครั้งที่การเชื่อมต่อขาด SDK จะรอสักครู่ ดึงข้อมูลที่ขาดไป และเชื่อมต่อใหม่ โดยเวลารอจะค่อย ๆ เพิ่มขึ้น ข้อความจะแสดงตามลำดับเสมอและไม่ซ้ำกัน หากการเชื่อมต่อแบบต่อเนื่องใช้งานไม่ได้ (เช่น อยู่หลังพร็อกซีขององค์กร) SDK จะเปลี่ยนไปตรวจสอบกับเซิร์ฟเวอร์เป็นระยะชั่วคราว
• เมื่อแอปทำงานในเบื้องหลัง การเชื่อมต่อจะปิดลง เมื่อกลับมาเปิดแอป SDK จะดึงข้อมูลที่ขาดไปและเชื่อมต่อใหม่ บทสนทนาที่ยังเปิดอยู่จะดำเนินต่อได้แม้ปิดแล้วเปิดแอปใหม่ ตราบใดที่ยังไม่เกิน 12 ชั่วโมง
• เวอร์ชันนี้ไม่มีการแจ้งเตือนแบบพุช ข้อความจะเข้ามาเฉพาะเมื่อเปิดแอปอยู่ คำตอบที่ส่งมาตอนแอปทำงานในเบื้องหลังจะแสดงทันทีเมื่อกลับมาเปิดแอป
• ข้อมูลสำหรับเข้าถึงบทสนทนาจะเก็บไว้ในหน่วยความจำ และจะเก็บในอุปกรณ์เฉพาะเมื่อเข้ารหัสด้วยคีย์จาก Android Keystore เท่านั้น ข้อมูลนี้จะไม่ถูกเขียนลงใน URL หรือบันทึกระบบ และจะถูกลบเมื่อบทสนทนาจบลง เปลี่ยนเป็นคำร้อง หรือหมดอายุ รวมถึงเมื่อเปลี่ยนผู้ใช้ด้วย setUser

สามารถใช้ Kavchat.controller.livePage เพื่อบอกเจ้าหน้าที่ว่าผู้ใช้มาจากหน้าจอใด

คำถาม เงื่อนไข และลีด

ไม่ต้องตั้งค่าในแอป สคริปต์สามารถขอข้อมูล (ชื่อ เบอร์โทรศัพท์ อีเมล ตัวเลข หรือข้อความอิสระ) เลือกวิธีดำเนินต่อจากข้อมูลที่มี และส่งลีดได้

• แป้นพิมพ์ที่เหมาะสม: เมื่อบอทรอคำตอบ ช่องข้อความจะแสดงแป้นพิมพ์สำหรับเบอร์โทรศัพท์ อีเมล หรือตัวเลข สำหรับคำถามชื่อ แป้นพิมพ์จะใช้ตัวพิมพ์ใหญ่ที่ต้นคำ หากคำตอบไม่ถูกต้อง บอทจะตอบด้วยข้อความสั้น ๆ ในภาษาของแชทและทำเครื่องหมายที่ช่องนั้น คำถามที่ข้ามได้จะแสดงปุ่ม "ข้าม" การพิมพ์ "ยกเลิก" ในภาษาที่รองรับจะออกจากคำถาม
• เบอร์โทรศัพท์: หมายเลขที่ไม่มี + จะใช้ประเทศเริ่มต้นของพื้นที่ทำงาน (กำหนดในการตั้งค่าบนหน้าจัดการ)
• ลีด: ขั้นตอนลีดจะแสดงข้อความขอความยินยอมพร้อมปุ่ม "ส่ง" และ "ไม่ ขอบคุณ" จากนั้นจะแสดงข้อความยืนยัน ลีดจะเข้าคิวในอุปกรณ์และส่งไปยังเซิร์ฟเวอร์ หากไม่มีการเชื่อมต่อเครือข่ายหรือเซิร์ฟเวอร์ไม่พร้อมใช้งาน ระบบจะลองส่งใหม่ (รวมถึงเมื่อเปิดแอปครั้งถัดไปและหลังเรียก reload()) เซิร์ฟเวอร์จะไม่รับรายการซ้ำ
• กรอกข้อมูลล่วงหน้า: แบบฟอร์มติดต่อและแบบฟอร์มขอคุยกับเจ้าหน้าที่จะกรอกชื่อ อีเมล และเบอร์โทรศัพท์ที่เก็บไว้ให้ล่วงหน้า ข้อมูลทั้งหมดที่เก็บไว้จะแนบไปกับคำร้องหรือคำขอคุยกับเจ้าหน้าที่ คำถามก่อนแชทกับเจ้าหน้าที่ (Premium) จะถามก่อนเชื่อมต่อ
• โทเค็นยืนยันตัวตน: เมื่อใช้ setUser ฟิลด์ name, email และ phone ในโทเค็นจะเติมคำตอบให้กับคำถามที่ตรงกัน และบอทจะข้ามคำถามเหล่านั้น
• หน้าจอปัจจุบัน: เงื่อนไขสามารถตรวจสอบหน้าจอปัจจุบันได้ โดยตั้งค่า Kavchat.controller.livePage (เช่น "checkout")

ค่าที่เก็บรวบรวมเป็นข้อมูลส่วนบุคคล ข้อมูลเหล่านี้จะอยู่ในบทสนทนาที่บันทึกไว้ในอุปกรณ์ และจะส่งไปเฉพาะลีด คำร้อง และแชทกับเจ้าหน้าที่เท่านั้น จะไม่ส่งไปยังรายงานเด็ดขาด

การทำงานแบบออฟไลน์และแคช

เวอร์ชันล่าสุดจะถูกเก็บไว้ใน SharedPreferences พร้อม ETag และตรวจสอบอีกครั้งด้วย If-None-Match (304) ทุกครั้งที่เปิดแอป เมื่อไม่มีเครือข่าย ระบบจะใช้สำเนาที่เก็บไว้และแสดงข้อความแจ้ง หากบอทปิดอยู่ เปิดให้เฉพาะผู้ใช้ทดสอบ หรือโควตาหมด จะไม่แสดงอะไร บทสนทนาที่ยังเปิดอยู่จะถูกเก็บไว้จนไม่มีการใช้งานนานถึง 30 นาที ดังนั้นการออกจากแชทหรือแอปจึงไม่ทำให้บทสนทนาเริ่มใหม่ ระบบจะรายงานเส้นทางการสนทนาหลังการดำเนินการล่าสุดสองวินาที และทันทีที่แอปทำงานในเบื้องหลัง