Android SDK

پیش‌نیازها#

• minSdk 24 (Android 7.0)، compileSdk 35.
• Kotlin 2.x و Jetpack Compose (این SDK رابط کاربری Compose را همراه خود دارد).
• JVM target 17.

خود SDK وابستگی‌های گذرای لازمش را می‌آورد (Coroutines، kotlinx.serialization، OkHttp، Coil، Compose) و مجوز INTERNET را در مانیفست خودش اعلام می‌کند — لازم نیست چیزی را دستی اضافه کنید.

نصب#

این کتابخانه در Maven Central با نام ai.respondo:respondo-sdk منتشر شده است. مطمئن شوید که mavenCentral() در مخزن‌های شما هست (در یک پروژهٔ تازهٔ Android به‌طور پیش‌فرض هست)، سپس وابستگی را با مختصات آن اضافه کنید.

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

dependencies {
    implementation("ai.respondo:respondo-sdk:0.1.0")
}

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

یک بار Respondo.init را صدا بزنید، یک بار RespondoChatHost() را در درخت Compose خود سوار کنید و چت را از دکمهٔ خودتان باز کنید.

import ai.respondo.sdk.Respondo
import ai.respondo.sdk.RespondoConfig
import ai.respondo.sdk.ui.RespondoChatHost

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        Respondo.init(
            context = this,
            config = RespondoConfig(
                agentId = "<agent-uuid>",   // از پنل مدیریت
                channelId = "<channel-uuid>", // اختیاری
                // baseUrl حذف شده -> https://api.respondo.ai
            ),
        )

        setContent {
            MaterialTheme {
                Box(modifier = Modifier.fillMaxSize()) {
                    Button(onClick = { Respondo.open() }) { Text("Support") }
                    RespondoChatHost() // وقتی وضعیت چت OPEN است، SDK برگه را نشان می‌دهد
                }
            }
        }
    }
}

همهٔ فراخوانی‌ها از سینگلتون Respondo می‌گذرند. این فراخوانی‌ها idempotent هستند، از هر thread امن‌اند، و آن‌هایی که پیش از پایان init انجام شوند بافر و سپس دوباره اجرا می‌شوند.

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

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

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

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

import ai.respondo.sdk.RespondoIdentity

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

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

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

Observableها و callbackها#

وضعیت را به‌صورت واکنشی با StateFlow بخوانید (عالی برای Compose) یا به‌صورت دستوری از راه RespondoListener (عالی برای نشان روی آیکون اپلیکیشن).

// واکنشی: شمار پیام‌های خوانده‌نشده به شکل StateFlow.
val unread by Respondo.unreadCount.collectAsState()

// دستوری: listener برای نشان‌ها و تحلیل‌ها.
Respondo.setListener(object : RespondoListener {
    override fun onUnreadChanged(count: Int) { updateAppIconBadge(count) }
    override fun onUrlRequested(url: String): Boolean = tryOpenInternally(url)
})

ردیابی صفحه#

در هر ناوبری، صفحهٔ جاری را گزارش کنید تا تیزرهای پیش‌دستانه و هدف‌گیری سطح صفحه بتوانند با آن تطبیق داده شوند. برای پاک‌کردن مقدار null بفرستید؛ با هر تغییر، تیزر پیش‌دستانه برای صفحهٔ تازه دوباره ارزیابی می‌شود.

Respondo.setCurrentScreen("pricing")

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

نوتیفیکیشن‌های پوش را برای پاسخ‌های آفلاین کارشناسان و تأیید هویت را برای کاربران واردشده راه بیندازید. کل سطح API، پوششِ Fragment برای میزبان‌های XML و رفع اشکال در راهنمای شروع به کار Android SDK آمده است؛ سورس‌های SDK روی GitHub عمومی‌اند.