iOS SDK

ข้อกำหนด#

• iOS 15.0+ (detent ของ sheet ละเอียดขึ้นบน iOS 16+ พร้อม fallback ของระบบสำหรับรุ่นต่ำกว่า)
• Swift 5.9+
• ไม่มี dependency จากภายนอก — มีเพียง Foundation, Swift Concurrency, SwiftUI และ UIKit

คุณ depend บน product RespondoSDK ซึ่ง re-export RespondoCore ที่ใช้ข้ามแพลตฟอร์ม

การติดตั้ง#

เพิ่ม package ด้วย Swift Package Manager ใน Xcode: File → Add Package Dependencies… แล้วป้อน https://github.com/respondo-app/sdk-ios, หรือประกาศใน Package.swift ของคุณเอง แล้ว depend บน product RespondoSDK

dependencies: [
    .package(url: "https://github.com/respondo-app/sdk-ios", from: "0.1.0")
],
targets: [
    .target(
        name: "MyApp",
        dependencies: [
            .product(name: "RespondoSDK", package: "sdk-ios")
        ]
    )
]

จากนั้น import ในโค้ด:

import RespondoSDK

เริ่มต้นใช้งาน#

เริ่มต้นหนึ่งครั้งตอนเปิดแอป แล้วเรียก Respondo.open() ที่ใดก็ได้ เมธอด lifecycle คือ initialize (คำว่า init ถูกสงวนไว้โดยภาษา)

import SwiftUI
import RespondoSDK

@main
struct MyApp: App {
    init() {
        Respondo.initialize(
            RespondoConfig(
                agentId: "<agent-uuid>",
                channelId: "<channel-uuid>"
                // baseUrl nil -> https://api.respondo.ai
            )
        )
    }

    var body: some Scene {
        WindowGroup {
            Button("Support") { Respondo.open() }
        }
    }
}

facade Respondo เป็น thread-safe การเรียกที่ทำทันทีหลังจาก initialize จะถูกเข้าคิวและนำไปใช้เมื่อ async init เสร็จสมบูรณ์

การระบุตัวตนผู้ใช้#

โดยค่าเริ่มต้นผู้เข้าชมทุกคนเป็นนิรนาม เมื่อเปิดครั้งแรก SDK จะสร้าง visitor_id ที่เสถียรและเก็บไว้ใน keychain ดังนั้นผู้ใช้ที่กลับมาจะพบบทสนทนาของตนอีกครั้ง ไม่มี API key ให้ฝัง — แต่ละบทสนทนาถูกปกป้องด้วย session token ต่อบทสนทนา ที่ backend สร้างขึ้นและเลื่อนไปข้างหน้าในทุกข้อความ ดังนั้นผู้เข้าชมนิรนามไม่ต้องยืนยันตัวตนใหม่

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

userHash คือลายเซ็นที่ backend ของคุณ คำนวณจาก identity_secret ของเอเจนต์ — HMAC-SHA256(secret, userId) (หรืออีเมลเมื่อไม่มี userId) เข้ารหัสเป็น hex ตัวพิมพ์เล็ก secret เป็นเครื่องพิสูจน์ว่าตัวตนนั้นเป็นของจริง จึงต้องอยู่บน backend ของคุณเท่านั้น และต้องไม่ถูกส่งไปในแอปเด็ดขาด ดูหน้า การยืนยันตัวตนสำหรับสูตรเต็มและตัวอย่างฝั่งเซิร์ฟเวอร์

// userHash มาจาก backend ของคุณ (HMAC-SHA256 บน userId) —
// อย่าคำนวณมันในแอป
Respondo.identify(
    RespondoIdentity(
        userId: session.userId,
        email: session.email,
        name: session.fullName,
        userHash: session.respondoUserHash
    )
)

// เมื่อออกจากระบบ: เพิกถอน session และเริ่มผู้เข้าชมนิรนามใหม่
Respondo.reset()

หากไม่มี hash หรือ hash ผิด จะไม่มีการโยน exception ใด ๆ: backend จะเก็บผู้เข้าชมให้เป็นนิรนามอย่างเงียบ ๆ แชทยังทำงานต่อไป และคุณเพียงเสียลิงก์ข้ามอุปกรณ์ จนกว่าจะมีการส่ง hash ที่ถูกต้องมา การยืนยันจะทำงานก็ต่อเมื่อเอเจนต์มี identity_secret ตั้งไว้ — ปล่อยว่างไว้ระหว่างการพัฒนา แล้ว userId / อีเมล จะถูกยอมรับตามที่เป็น

Observable และ delegate#

อ่านสถานะเป็น getter แบบ synchronous, เป็น AsyncStream แบบ reactive หรือผ่าน RespondoDelegate. stream และ callback ของ delegate จะมาถึงบน main actor

// stream แบบ reactive ของจำนวนที่ยังไม่อ่าน
Task {
    for await count in Respondo.unreadCountStream {
        updateBadge(count)
    }
}

// delegate สำหรับ badge และ fallback ของ deep-link
final class SupportCoordinator: RespondoDelegate {
    init() { Respondo.delegate = self }
    func respondoUnreadChanged(_ count: Int) {
        UIApplication.shared.applicationIconBadgeNumber = count
    }
}

การติดตามหน้าจอ#

รายงานหน้าจอปัจจุบันในทุกการนำทาง เพื่อให้ teaser เชิงรุกและการกำหนดเป้าหมายระดับหน้าจับคู่กับมันได้ (static func setCurrentScreen(_ name: String?)) ส่ง nil เพื่อล้างค่า; ในแต่ละการเปลี่ยนแปลง teaser เชิงรุกจะถูกประเมินใหม่สำหรับหน้าจอใหม่

ชื่อเดียวกันนี้ใช้เทียบกับกฎหน้าจอของแบบสำรวจป๊อปอัป จึงควรใช้ตัวระบุที่คงที่ เช่น «Checkout» แทนชื่อที่แปลแล้ว กฎที่อยู่หน้าเว็บใช้กับเว็บไซต์เท่านั้น

Respondo.setCurrentScreen("pricing")

เปิดแบบสำรวจจากโค้ด#

เปิดแบบสำรวจป๊อปอัปที่เผยแพร่อยู่ทันที ไม่ว่าผู้ใช้จะอยู่หน้าจอใด โดยข้าม Show on กฎของหน้าจอ เวลาบนหน้าจอ อีเวนต์ทริกเกอร์ และกลุ่มเป้าหมาย คัดลอก id จากตัวแก้ไขแบบสำรวจ (Additional ways to share) แบบสำรวจที่ผู้ใช้ตอบแล้วจะไม่แสดงอีก

Respondo.startSurvey("<survey-id>")

ขั้นตอนถัดไป#

เชื่อมต่อ พุชการแจ้งเตือน และ การยืนยันตัวตนUIKit wrapper RespondoChatViewController, ผิวสัมผัส delegate เต็มรูปแบบ และการแก้ปัญหา ครอบคลุมอยู่ในคู่มือเริ่มต้นใช้งาน iOS SDK; ซอร์สของ SDK เปิดเป็นสาธารณะบน GitHub