Android SDK

דרישות#

• minSdk 24 (Android 7.0), compileSdk 35.
• Kotlin 2.x ו-Jetpack Compose (ה-SDK כולל Compose UI).
• יעד JVM 17.

ה-SDK מושך את התלויות הטרנזיטיביות שלו בעצמו (Coroutines, kotlinx.serialization, OkHttp, Coil, Compose) ומצהיר על הרשאת INTERNET ב-manifest שלו — אין מה להוסיף ידנית.

התקנה#

הספרייה מפורסמת ב- 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() // ה-SDK מציג את הגיליון כשמצב הצ׳אט הוא OPEN
                }
            }
        }
    }
}

כל הקריאות עוברות דרך ה-singleton Respondo. הן אידמפוטנטיות, בטוחות מכל thread, וקריאות שנעשות לפני שהאתחול מסתיים נצברות ומופעלות מחדש.

זיהוי משתמשים#

כברירת מחדל כל מבקר הוא אנונימי. בהפעלה הראשונה ה-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()

אם ה-hash חסר או שגוי, שום דבר לא נזרק כשגיאה: ה-backend שומר את המבקר אנונימי בשקט, הצ׳אט ממשיך לעבוד, ואתם פשוט מאבדים את הקישור החוצה-מכשירי עד שיסופק hash תקין. האימות רץ רק כאשר לסוכן מוגדר identity_secret — השאירו אותו ריק בזמן הפיתוח ואז userId / אימייל מתקבלים כמות שהם.

Observables וקריאות חוזרות#

קראו את המצב באופן ריאקטיבי כ- 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.