Kavchat by maxsave
เมนูคู่มือ

iOS

แพ็กเกจ Swift ของ Kavchat เพิ่มบอตบริการลูกค้าที่ทำงานตามสคริปต์ให้แอป iOS พร้อมคอมโพเนนต์ SwiftUI และ UIKit คำตอบเป็นไปตามที่กำหนดไว้ และยังทำงานได้แม้ไม่มีอินเทอร์เน็ต โดยใช้เวอร์ชันล่าสุดที่เผยแพร่ ต้องใช้ iOS 15 ขึ้นไป

แพ็กเกจนี้มีสองผลิตภัณฑ์: KavchatEngine ซึ่งเป็นเอนจินการสนทนาเวอร์ชัน Swift ที่ไม่ใช้ UIKit และ Kavchat ซึ่งรวมการเชื่อมต่อเครือข่าย แคชบนอุปกรณ์ และส่วนติดต่อผู้ใช้: KavchatChatView (SwiftUI), KavchatLauncher และ KavchatViewController (UIKit)

การติดตั้ง

ใช้ Swift Package Manager ใน Xcode: เลือก ไฟล์ > เพิ่มแพ็กเกจที่ใช้ แล้วป้อน URL ของที่เก็บโค้ด:

Package URL
https://bitbucket.org/maxsave/kavchat-ios.git

หรือเพิ่มในไฟล์ Package.swift:

Package.swift
.package(url: "https://bitbucket.org/maxsave/kavchat-ios.git", from: "0.0.11"),
// ...
.product(name: "Kavchat", package: "kavchat-ios"),

SDK เป็นโอเพนซอร์สภายใต้สัญญาอนุญาต MIT: bitbucket.org/maxsave/kavchat-ios

การตั้งค่า

เรียก configure ครั้งเดียวให้เร็วที่สุดเท่าที่ทำได้ เช่น ใน init ของ App หรือใน application(_:didFinishLaunchingWithOptions:):

Swift
import Kavchat

Kavchat.configure(publicKey: "pk_live_...")            // the public key from the dashboard
// Optional:
// Kavchat.configure(publicKey: "pk_live_...", apiBase: "https://api.kavchat.com", locale: "he")

สามารถใส่คีย์สาธารณะไว้ในแอปได้ แต่ห้ามใส่คีย์ลับ (sk_live_...) ไว้ในแอปโดยเด็ดขาด

SwiftUI

ปุ่มลอยที่มุมซึ่งเลือกไว้ในแดชบอร์ด ใช้เปิดแชตในหน้าต่างแบบ sheet:

SwiftUI
ContentView()
    .kavchatLauncher()

จะวางปุ่มเอง หรือฝังแชตไว้ในหน้าจอของแอปก็ได้:

SwiftUI
KavchatLauncher()
KavchatChatView()                                      // full chat, no close button
KavchatChatView(onClose: { showChat = false })         // with a close button

เปิดและปิดหน้าต่างของปุ่มลอยผ่านโค้ดด้วย Kavchat.open() และ Kavchat.close()

UIKit

UIKit
Kavchat.present(from: self)                            // modal, with a close button
// or
let chat = KavchatViewController(showsCloseButton: false)
navigationController?.pushViewController(chat, animated: true)

โทเค็นระบุตัวตน

ระบุตัวผู้ใช้ที่เข้าสู่ระบบด้วย JWT ที่เซิร์ฟเวอร์ของคุณลงนามด้วยคีย์ลับ (ดู การระบุตัวผู้ใช้) โทเค็นจะถูกส่งในส่วนหัว Authorization: Bearer <token> ผู้ใช้ที่ระบุตัวตนแล้วสามารถดูเวอร์ชันที่เปิดให้เฉพาะผู้ทดสอบ และส่งแบบฟอร์มติดต่อได้โดยไม่ต้องระบุอีเมลหรือเบอร์โทรศัพท์

Swift
Kavchat.setUser(token: identityToken, name: "Dana")    // after login
Kavchat.setUser(token: nil)                            // after logout

เมื่อเปลี่ยนผู้ใช้ ระบบจะโหลดเวอร์ชันใหม่และเริ่มการสนทนาใหม่ เพื่อไม่ให้การสนทนาของผู้ใช้คนหนึ่งปรากฏให้ผู้ใช้อีกคนเห็น

หน้าจอในแอป: onScreen

ปุ่มประเภท screen ในสคริปต์จะขอให้แอปเปิดหน้าจอใดหน้าจอหนึ่งของแอป โดยหน้าต่างแชตจะปิดก่อนเพื่อให้มองเห็นหน้าจอนั้น:

Swift
Kavchat.onScreen = { screen, targetId in
    router.open(screen, id: targetId)                  // e.g. "orders", "42"
}

หากไม่มีตัวจัดการ ปุ่มเหล่านี้จะไม่ทำอะไร ปุ่ม link เปิดได้เฉพาะลิงก์ https และ tel สำหรับการวิเคราะห์ข้อมูล Kavchat.onEvent จะรายงานเหตุการณ์ ready, unavailable, open, close, effect และ ticket

รายการหน้าจอในตัวแก้ไข

ประกาศหน้าจอที่แอปเปิดได้เพียงครั้งเดียวใน Kavchat.configure(..., screens:) SDK จะส่งรายการไปยัง Kavchat โดยอัตโนมัติ แล้วตัวแก้ไขสคริปต์จะแสดงชื่อหน้าจอเหล่านี้ในรายการแบบเลื่อนลงแทนช่องข้อความอิสระ ตัวแก้ไขยังขอรหัสรายการเมื่อหน้าจอต้องใช้ และเตือนเมื่อมีปุ่มที่นำไปยังหน้าจอที่ยังไม่ได้ประกาศไว้ จึงไม่ต้องมีใครพิมพ์รายการหน้าจอเองในแดชบอร์ด

Swift
Kavchat.configure(publicKey: "pk_live_...", screens: [
    KavchatScreen(id: "orders", label: "My orders"),
    KavchatScreen(id: "product", label: "Product page", needsTarget: true),  // needs a targetId
])
// or later: Kavchat.registerScreens([...])
  • id คือค่าที่ส่งไปยัง onScreen: ใช้ตัวอักษรละติน ตัวเลข _, . และ - ได้สูงสุด 40 อักขระ ส่วน label คือชื่อที่ผู้ดูแลเห็น ยาวได้สูงสุด 60 อักขระ รองรับสูงสุด 100 หน้าจอ รายการที่ไม่ถูกต้องและรหัสที่ซ้ำกันจะถูกตัดออก
  • needsTarget: ปุ่มจะมีรหัสรายการแนบมาด้วย (เช่น รหัสสินค้า) และ onScreen จะรับค่านี้เป็น targetId
  • รายการจะถูกส่งในเบื้องหลังหลังจากโหลดเวอร์ชันแล้ว เฉพาะเมื่อมีการเปลี่ยนแปลงหรือสัปดาห์ละครั้ง หากส่งไม่สำเร็จจะไม่มีการแจ้งเตือน และจะลองส่งอีกครั้งเมื่อเปิดแอปครั้งถัดไป ผู้ใช้จะไม่เห็นอะไร
  • หน้าจอที่ลงทะเบียนไว้จะแสดงในแดชบอร์ดที่ บอต, การตั้งค่า, "หน้าจอของแอป" พร้อมแพลตฟอร์มที่รายงานแต่ละหน้าจอ หากนำหน้าจอออกจากแอปแล้ว สามารถลบออกจากรายการที่นี่ได้

สี

สีจะใช้ค่าจากแดชบอร์ด (primaryColor) ข้อความบนพื้นสีแบรนด์จะแสดงเป็นสีขาวหรือสีเกือบดำตามเกณฑ์ความต่างสีของ WCAG หากสีอ่อนเกินไปสำหรับข้อความบนพื้นขาว ลิงก์และปุ่มจะใช้สีเกือบดำแทน ชื่อบอต ข้อความรอง รูปภาพ และด้านที่วางปุ่มลอย (start หรือ end) ก็มาจากแดชบอร์ดเช่นกัน จึงเปลี่ยนได้โดยไม่ต้องอัปเดตแอป

ป้าย "ขับเคลื่อนโดย Kavchat by maxsave" จะแสดงในทุกแพ็กเกจ พร้อมลิงก์ไปยัง kavchat.com สำหรับ Premium สามารถซ่อนป้ายนี้ได้ในการตั้งค่าบอต

ภาษาและ RTL

  • ภาษาของส่วนติดต่อผู้ใช้จะใช้ค่า locale ที่ส่งให้ configure หากไม่ได้ส่งค่า จะใช้ภาษาของอุปกรณ์ถ้ามีคำแปลรองรับ (he, en, ar, ru, es, fr, de, pt, it, tr) ถัดไปคือภาษาของสคริปต์ และสุดท้ายคือภาษาอังกฤษ
  • การจับคู่กับสคริปต์จะใช้ภาษาของสคริปต์เสมอ (คำทั่วไปที่ข้ามไป รวมถึงคำเติมหน้าในภาษาฮีบรูและอาหรับ)
  • สำหรับภาษาฮีบรูและอาหรับ layoutDirection ของทั้งแชตจะเป็นจากขวาไปซ้าย ไม่มีการกลับด้านด้วยตนเอง หากใช้คอมโพเนนต์อื่นครอบคอมโพเนนต์เหล่านี้ ให้ใช้ leading และ trailing

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

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

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

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

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

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

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

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

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

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

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

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

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