مستندات

iOS SDK

یک کلاینت بومی بر پایهٔ Swift و SwiftUI برای چت پشتیبانی Respondo، بدون هیچ وابستگی جانبی.

پیش‌نیازها#

  • iOS 15.0+ (تنظیم دقیق‌تر ارتفاع برگه در iOS 16+، با جایگزین سیستمی در نسخه‌های پایین‌تر).
  • Swift 5.9+.
  • بدون هیچ وابستگی جانبی — فقط Foundation، Swift Concurrency، SwiftUI و UIKit.

شما به محصول RespondoSDK وابسته می‌شوید که خودش RespondoCore چندسکویی را دوباره صادر می‌کند.

نصب#

بسته را با Swift Package Manager اضافه کنید. در Xcode: File → Add Package Dependencies… و بعد این نشانی را وارد کنید: https://github.com/respondo-app/sdk-ios. یا آن را در Package.swift خودتان اعلام کنید و سپس به محصول RespondoSDK وابسته شوید.

Package.swiftswift
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 کنید:

Swiftswift
import RespondoSDK

راه‌اندازی اولیه#

یک بار هنگام اجرای اپلیکیشن مقداردهی کنید، بعد هر جا خواستید Respondo.open() را صدا بزنید. متد چرخهٔ عمر initialize نام دارد (واژهٔ init در خود زبان رزرو شده است).

MyApp.swiftswift
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() }
        }
    }
}

نمای Respondo در برابر چند-نخی امن است. فراخوانی‌هایی که بلافاصله پس از initialize انجام شوند در صف می‌مانند و همین‌که مقداردهی ناهم‌زمان تمام شد اعمال می‌شوند.

شناسایی کاربران#

به‌طور پیش‌فرض هر بازدیدکننده ناشناس است. در نخستین اجرا، SDK یک visitor_id پایدار می‌سازد و آن را در keychain نگه می‌دارد، پس کاربری که برمی‌گردد دوباره گفت‌وگوی خودش را پیدا می‌کند. هیچ کلید API‌ای برای جاسازی وجود ندارد — هر گفت‌وگو با یک توکن نشستِ مخصوصِ همان گفت‌وگو محافظت می‌شود که backend صادرش می‌کند و با هر پیام جلو می‌برد، پس بازدیدکنندهٔ ناشناس هرگز مجبور نیست دوباره احراز هویت کند.

همین‌که کاربرتان وارد شد، identify را صدا بزنید. این کار هویت واقعی او را متصل می‌کند تا تاریخچه‌اش میان دستگاه‌ها و نصب‌های دوباره همراهش بماند و نام و ایمیلش به‌جای یک بازدیدکنندهٔ ناشناس کنار گفت‌وگو در صندوق ورودی شما دیده شود.

userHash امضایی است که backend شما از identity_secret عامل حساب می‌کند — HMAC-SHA256(secret, userId) (یا ایمیل، وقتی userId وجود ندارد)، کدشده به‌صورت hex با حروف کوچک. این راز ثابت می‌کند که هویت اصیل است، پس باید فقط روی backend شما بماند و هرگز داخل اپلیکیشن منتشر نشود. فرمول کامل و نمونه‌های سمت سرور در صفحهٔ تأیید هویت آمده است.

Swiftswift
// مقدار userHash از backend شما می‌آید (HMAC-SHA256 روی userId) —
// هرگز آن را داخل اپلیکیشن حساب نکنید.
Respondo.identify(
    RespondoIdentity(
        userId: session.userId,
        email: session.email,
        name: session.fullName,
        userHash: session.respondoUserHash
    )
)

// هنگام خروج: نشست را باطل کنید و یک بازدیدکنندهٔ ناشناس تازه شروع کنید.
Respondo.reset()

اگر هش نباشد یا نادرست باشد، چیزی خطا نمی‌دهد: backend بی‌سروصدا بازدیدکننده را ناشناس نگه می‌دارد، چت به کارش ادامه می‌دهد و شما فقط پیوند بین‌دستگاهی را از دست می‌دهید تا وقتی هش معتبری داده شود. تأیید تنها زمانی اجرا می‌شود که برای عامل identity_secret تنظیم شده باشد — در زمان توسعه آن را خالی بگذارید تا userId / ایمیل همان‌طور که هستند پذیرفته شوند.

Observableها و delegate#

وضعیت را با getterهای هم‌زمان، با AsyncStreamهای واکنشی یا از راه یک RespondoDelegate بخوانید. استریم‌ها و فراخوانی‌های delegate روی main actor می‌رسند.

Swiftswift
// جریان واکنشی شمار پیام‌های خوانده‌نشده.
Task {
    for await count in Respondo.unreadCountStream {
        updateBadge(count)
    }
}

// delegate برای نشان‌ها و جایگزین‌های deep link.
final class SupportCoordinator: RespondoDelegate {
    init() { Respondo.delegate = self }
    func respondoUnreadChanged(_ count: Int) {
        UIApplication.shared.applicationIconBadgeNumber = count
    }
}

ردیابی صفحه#

در هر ناوبری، صفحهٔ جاری را گزارش کنید تا تیزرهای پیش‌دستانه و هدف‌گیری سطح صفحه بتوانند با آن تطبیق داده شوند (static func setCurrentScreen(_ name: String?)). برای پاک‌کردن مقدار nil بفرستید؛ با هر تغییر، تیزر پیش‌دستانه برای صفحهٔ تازه دوباره ارزیابی می‌شود.

Swiftswift
Respondo.setCurrentScreen("pricing")

گام‌های بعدی#

نوتیفیکیشن‌های پوش و تأیید هویت را راه بیندازید. پوشش UIKit یعنی RespondoChatViewController، کل سطح delegate و رفع اشکال در راهنمای شروع به کار iOS SDK آمده است؛ سورس‌های SDK روی GitHub عمومی‌اند.