Android SDK

المتطلبات#

• minSdk 24 (Android 7.0)، وcompileSdk 35.
• Kotlin 2.x وJetpack Compose (تأتي الحزمة مع واجهة Compose).
• هدف JVM 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
                }
            }
        }
    }
}

تمر جميع النداءات عبر الكائن المفرد Respondo. وهي مثالية التكرار (idempotent)، وآمنة من أي خيط تنفيذ، وتُخزَّن النداءات التي تُجرى قبل اكتمال التهيئة ثم يُعاد تشغيلها.

تعريف المستخدمين#

افتراضياً يكون كل زائر مجهولاً. عند الإطلاق الأول تولّد حزمة SDK visitor_id ثابتاً وتحتفظ به في التخزين المحلي، فيجد المستخدم العائد محادثته من جديد. لا يوجد مفتاح API لتضمينه — إذ تُحمى كل محادثة برمز جلسة خاص بها يصكّه الخلفية ويدفعه إلى الأمام مع كل رسالة، فلا يضطر الزائر المجهول قط إلى إعادة المصادقة.

استدعِ identify بمجرد تسجيل دخول مستخدمك. يربط ذلك هويته الحقيقية بحيث يتبعه سجلّه عبر الأجهزة وعمليات إعادة التثبيت، ويظهر اسمه وبريده الإلكتروني بجوار المحادثة في صندوق الوارد لديك بدلاً من زائر مجهول.

الـ userHash هو توقيع تحسبه خلفيتك من identity_secret الخاص بالوكيل — HMAC-SHA256(secret, userId) (أو البريد الإلكتروني حين لا يوجد userId)، مُرمَّزاً كنظام ست عشري بأحرف صغيرة. يثبت السر أن الهوية أصيلة، لذا يجب أن يبقى على خلفيتك فقط ولا يُشحن أبداً في التطبيق. راجع صفحة التحقق من الهوية للاطلاع على الصيغة الكاملة وأمثلة جانب الخادم.

import ai.respondo.sdk.RespondoIdentity

// يأتي userHash من خلفيتك (HMAC-SHA256 على userId) —
// لا تحسبه أبداً داخل التطبيق.
Respondo.identify(
    RespondoIdentity(
        userId = session.userId,
        email = session.email,
        name = session.fullName,
        userHash = session.respondoUserHash,
    ),
)

// عند تسجيل الخروج: أسقط رمز الدفع، وأبطل الجلسة، وابدأ زائراً مجهولاً جديداً.
Respondo.clearPushToken()
Respondo.reset()

إذا كان التجزئة مفقودة أو خاطئة، فلا يُلقى أي استثناء: تُبقي الخلفية الزائر مجهولاً بصمت، وتستمر المحادثة في العمل، وتفقد ببساطة الربط عبر الأجهزة حتى يُقدَّم تجزئة صالحة. لا يعمل التحقق إلا عندما يكون للوكيل identity_secret مضبوط — اتركه فارغاً أثناء التطوير ويُقبل userId / البريد الإلكتروني كما هما.

Observables والاستدعاءات الراجعة#

اقرأ الحالة تفاعلياً على هيئة StateFlow (مناسب جداً لـ Compose) أو أمرياً عبر RespondoListener (مناسب جداً لشارة أيقونة التطبيق).

// تفاعلي: عدد غير المقروء على هيئة StateFlow.
val unread by Respondo.unreadCount.collectAsState()

// أمري: مستمع للشارات والتحليلات.
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؛ ومصادر الحزمة متاحة للعموم على GitHub.