دليل Android SDK من هدهد: دعم أصلي داخل تطبيقك في ١٠ دقائق

لديك تطبيق أندرويد، ويطرح عملاؤك أسئلتهم داخله. أبسط خيار هو فتح أداة الدردشة الخاصة بالويب داخل WebView. لكن إذا كان يهمك المظهر الأصلي، ولوحة المفاتيح وأدوات اختيار المرفقات في أندرويد، وإحساس التطبيق الحقيقي، فإن Android SDK من هدهد يؤدي المهمة نفسها دون WebView. فهو يتصل بصندوق الوارد نفسه وبواجهة API نفسها التي تستخدمها أداة الويب، لذا تصل المحادثات والتذاكر القادمة من التطبيق إلى صندوق الوارد المشترك نفسه.

في هذا الدليل نربط تطبيق Kotlin بالـ SDK خطوة بخطوة: التثبيت، والإعداد، وفتح الدردشة، وتعريف المستخدم، والمظهر واللغة، وعدّاد الرسائل غير المقروءة. وفي النهاية ستعرف كيف تعمل التذاكر واستبيان الرضا، وكيف تعالج الأخطاء الشائعة.

الإصدار الحالي من الـ SDK تجريبي (1.0.0-beta04). أسماء الفئات والمعاملات الواردة أدناه مأخوذة من هذا الإصدار، وقد تتغير قبل الإصدار المستقر.

الـ SDK أم أداة الويب داخل WebView؟

إذا كان تطبيقك مجرد صفحة ويب داخل غلاف أندرويد، فإن أداة الويب تكفي. أما إذا كان تطبيقك أصليًا والدعم جزء من تجربته، فالـ SDK هو الخيار الأفضل.

ماذا يتضمن الـ SDK

• أنماط التواصل في صندوق الوارد: دردشة مباشرة، أو تذكرة، أو الاثنان معًا، أو «تذكرة عند عدم التوفر». الإعداد الذي اخترته لأداة الويب في اللوحة ينطبق في التطبيق أيضًا.
• التذاكر: نموذج تذكرة يضم الموضوع والوصف والفئة والمرفقات (حسب إعدادات صندوق الوارد)، وقائمة «تذاكري»، ومحادثة كل تذكرة مع شارة الحالة والردود.
• استبيان الرضا (CSAT): ثلاثة أنماط للعرض: الوجوه التعبيرية، والنجوم، والأرقام من ١ إلى ٥، مع مربع تعليق اختياري.
• إعلانات وتحذيرات القناة (منذ 1.0.0-beta04): تظهر الإعلانات نفسها الموجودة في أداة الويب في أعلى شاشة البداية، دون أي كود إضافي.
• نموذج ما قبل الدردشة، وساعات العمل والعطلات، وشريط تنبيه المشكلات، وإنهاء المحادثة وإرسال نسخة منها بالبريد الإلكتروني، كما في أداة الويب.
• ست لغات: الفارسية والإنجليزية والعربية والألمانية والإسبانية والفرنسية. وتعود اللغات الأخرى إلى الإنجليزية.
• المظهر الفاتح والداكن، ولون علامة صندوق الوارد، وإمكانية تجاوز اللون يدويًا.
• انقطاع الاتصال: عند انقطاع الشبكة أو الـ WebSocket يظهر شريط «لا يوجد اتصال»، ويعيد الـ SDK الاتصال تلقائيًا، وتبقى الرسالة التي فشل إرسالها مع زر «إعادة المحاولة».

المتطلبات

• قناة تواصل من نوع «الموقع الإلكتروني» في لوحة هدهد. إن لم تكن لديك قناة بعد، فاتبع دليل تثبيت الدردشة المباشرة حتى مرحلة إنشاء القناة.
• قيمة websiteToken الخاصة بالقناة. وهي القيمة نفسها الموجودة في كود الأداة.
• minSdk بقيمة ٢٤ أو أعلى، وKotlin وJava 17. يُبنى الـ SDK بـ compileSdk 35، وواجهته مبنية على Jetpack Compose. وإذا كان تطبيقك ما زال يستخدم Views، فاستدعِ Hodhod.open لاستخدام الـ Activity الجاهزة؛ وتُضاف اعتمادات Compose تلقائيًا.

الخطوة ١: أضف الاعتماد

للـ SDK وحدتان: hodhod-core (بلا واجهة: API والاتصال المباشر والمنطق) وhodhod-ui (واجهة Compose وActivity جاهزة). تسحب hodhod-ui الوحدة hodhod-core معها، فللحصول على الواجهة الجاهزة تكفي هذه الوحدة وحدها.

الـ SDK مفتوح المصدر (MIT) على github.com/HodHodChat/hodhod-android-sdk ويُثبَّت عبر JitPack الذي يبنيه من وسم git ‏1.0.0-beta04 في المستودع. أضف أولًا مستودع JitPack إلى settings.gradle.kts:

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
    }
}

ثم أضف الاعتماد:

// app/build.gradle.kts
dependencies {
    implementation("com.github.HodHodChat.hodhod-android-sdk:hodhod-ui:1.0.0-beta04")
}

الإحداثيات هي com.github.HodHodChat.hodhod-android-sdk:hodhod-ui:1.0.0-beta04 (و...:hodhod-core:1.0.0-beta04 إن احتجت النواة بلا واجهة فقط). تبقى أسماء حزم Kotlin في شيفرتك chat.hodhod.sdk.

الخطوة ٢: اضبط الإعدادات في فئة Application

اضبط الـ SDK مرة واحدة في Application.onCreate. ولا يرسل الـ SDK أي طلبات شبكة إلى أن يُستدعى Hodhod.start() أو Hodhod.open() أو Hodhod.identify().

import android.app.Application
import chat.hodhod.sdk.Hodhod
import chat.hodhod.sdk.HodhodConfig

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        Hodhod.configure(
            this,
            HodhodConfig(
                baseUrl = "https://hodhod.chat",          // your Hodhod server, no extra path
                websiteToken = "YOUR_WEBSITE_TOKEN",      // the website inbox token
            ),
        )
        Hodhod.start() // optional: so the unread counter works before the chat is opened
    }
}

سجّل الفئة في AndroidManifest.xml بإضافة android:name=".MyApp" إلى وسم <application>. يجب أن يبدأ العنوان الأساسي بـ https://؛ والاستثناء الوحيد هو الخادم المحلي في إصدارات debug، وسيأتي شرحه في قسم «استكشاف الأخطاء وإصلاحها».

الخطوة ٣: افتح الدردشة

هناك أربع طرق، نبدأ فيها بالأبسط.

١. الـ Activity الجاهزة. سطر واحد من أي Activity أو Fragment:

Hodhod.open(context)

تفتح هذه الطريقة HodhodChatActivity: صفحة بملء الشاشة بمظهر معزول عن مظهر تطبيقك، وتتولى زر الرجوع بنفسها. وتُفتح الصفحة نفسها أيضًا عبر الرابط العميق hodhod://chat.

٢. ضمّها في شاشة Compose الخاصة بك. إذا أردت أن تكون الدردشة داخل التنقل في تطبيقك:

@Composable
fun SupportScreen(onBack: () -> Unit) {
    HodhodChat(modifier = Modifier.fillMaxSize(), onClose = onBack)
}

يعرض HodhodChat الشاشة الرئيسية والدردشة والتذاكر ونموذج ما قبل الدردشة بحسب إعدادات صندوق الوارد، ويستدعي onClose عندما يغادر المستخدم الشاشة الأولى أو يضغط زر الإغلاق. وإذا كنت بحاجة إلى مراعاة شريط الحالة وشريط التنقل، فعالج الـ insets في modifier؛ وهذا ما تفعله HodhodChatActivity عبر windowInsetsPadding(WindowInsets.systemBars).

٣. زر عائم بشارة غير المقروء. HodhodBubble زر دائري يعرض عدد الرسائل غير المقروءة ويستدعي Hodhod.open عند النقر:

Box(Modifier.fillMaxSize()) {
    // screen content
    HodhodBubble(Modifier.align(Alignment.BottomEnd).padding(16.dp))
}

مرّر onClick إذا أردت سلوكًا مختلفًا. ويأتي لون الزر من صندوق الوارد، أو يمكنك تغييره عبر المعامل accent.

٤. زرك الخاص. أي زر بتصميم تطبيقك، مثل «الدعم» في شاشة الملف الشخصي، يكفي أن يستدعي Hodhod.open(context).

الخطوة ٤: عرّف المستخدم

إذا كان المستخدم مسجّلًا الدخول إلى تطبيقك، فعرّفه إلى هدهد لتُسجَّل المحادثات والتذاكر باسمه ويمكن الوصول إليها من جهاز آخر أيضًا:

Hodhod.identify(
    HodhodUser(
        identifier = user.id,                // a stable user id in your system
        identifierHash = hashFromBackend,    // HMAC computed on your backend
        name = user.name,
        email = user.email,
        phone = user.phone,
        customAttributes = mapOf("plan" to "pro"),
    )
) { result ->
    result.onFailure { Log.w("Support", "identify failed: ${it.message}") }
}

بدون identifier يكون المستخدم جهة اتصال مجهولة. وتُسلَّم النتيجة على الخيط الرئيسي.

لماذا identifierHash، ولماذا في الخادم الخلفي؟

لو استطاع أي شخص إرسال معرّف شخص آخر، لأمكنه قراءة محادثات ذلك الشخص. ولمنع ذلك يحتفظ هدهد بمفتاح HMAC سري لكل قناة تواصل (في إعدادات القناة، ضمن «التحقق من هوية المستخدم»)، ويتحقق من identifierHash على النحو التالي: HMAC بخوارزمية SHA-256 للقيمة identifier باستخدام ذلك المفتاح، بصيغة سلسلة سداسية عشرية (hex).

يجب ألا يكون المفتاح داخل التطبيق أبدًا. فبعد تسجيل دخول المستخدم، لا يحصل التطبيق من الخادم الخلفي لديك إلا على قيمة identifierHash. إليك مثالان:

// Node.js
import { createHmac } from 'node:crypto';

const identifierHash = createHmac('sha256', process.env.HODHOD_HMAC_KEY)
  .update(String(user.id))
  .digest('hex');

# Python
import hashlib, hmac, os

identifier_hash = hmac.new(
    os.environ["HODHOD_HMAC_KEY"].encode(),
    str(user.id).encode(),
    hashlib.sha256,
).hexdigest()

وفي PHP الأمر نفسه: hash_hmac('sha256', (string) $user->id, $key). ويجب أن تكون سلسلة identifier متطابقة تمامًا في التطبيق وفي الخادم الخلفي.

إذا فعّلت «فرض التحقق من هوية المستخدم» في إعدادات القناة، فستُرفض الطلبات التي لا تتضمن identifierHash. ننصح بتفعيله حتى لا يصل أحد إلى محادثات شخص آخر بتخمين معرّفه.

الخصائص المخصصة وتسجيل الخروج

أرسل الخصائص المخصصة (مثل إصدار التطبيق أو الباقة) مع HodhodUser أو بشكل منفصل. وتُحفظ في طابور إلى أن تتوفر الجلسة:

Hodhod.setCustomAttributes(mapOf("app_version" to BuildConfig.VERSION_NAME))

وعندما يسجّل المستخدم الخروج من تطبيقك:

Hodhod.logout()

يمسح هذا الاستدعاء الجلسة والرموز المخزّنة ويغلق الاتصال؛ وفي الاستخدام التالي تُنشأ جهة اتصال مجهولة جديدة. وبذلك لا يرى الشخص التالي الذي يسجّل الدخول على الهاتف نفسه محادثات المستخدم السابق.

الخطوة ٥: المظهر واللغة والوضع الداكن

كل ذلك يُضبط في HodhodConfig:

HodhodConfig(
    baseUrl = "https://hodhod.chat",
    websiteToken = "YOUR_WEBSITE_TOKEN",
    locale = "fa",                       // fa, en, ar, de, es or fr
    darkMode = DarkMode.AUTO,            // AUTO (system), LIGHT or DARK
    accentColorOverride = 0xFF6A2BC4,    // an ARGB color instead of the inbox widget color
)

• اللغة: تكون الأولوية لـ locale في الإعدادات، ثم للغة الحساب على الخادم، ثم للغة الجهاز. وتعود اللغة غير المدعومة إلى الإنجليزية. ويُضبط اتجاه التخطيط (RTL للفارسية والعربية) تلقائيًا.
• المظهر: يتبع AUTO إعداد النظام.
• اللون: إذا لم تمرّر accentColorOverride، يُستخدم لون الأداة الذي ضبطته لصندوق الوارد في اللوحة.

الخطوة ٦: عدّاد الرسائل غير المقروءة

عدد الرسائل غير المقروءة هو StateFlow<Int>. ويبقى صفرًا إلى أن يُستدعى Hodhod.start() أو Hodhod.open()، ولهذا أضفنا start() في الخطوة ٢. ويتحدّث العدّاد مباشرة أثناء عمل تطبيقك.

val unread by Hodhod.unreadCount.collectAsState()

BadgedBox(badge = { if (unread > 0) Badge { Text("$unread") } }) {
    Icon(Icons.Outlined.SupportAgent, contentDescription = "Support")
}

وإذا كنت تستخدم HodhodBubble، فهو يعرض هذا العدّاد بنفسه. أما حالة تحميل الإعدادات ففي Hodhod.state (Idle أو Loading أو Ready أو Failed).

كيف تعمل التذاكر والاستبيان في التطبيق

تتحكم في هذه السلوكيات إعدادات صندوق الوارد في اللوحة، ولا تحتاج إلى أي كود:

• نمط التواصل: في نمط «الدردشة» يدخل العميل مباشرة إلى محادثة، وفي نمط «التذكرة» يرى نموذج التذكرة، وفي نمط «الاثنين معًا» يختار أحدهما. وفي «تذكرة عند عدم التوفر» تُعرض الدردشة المباشرة أثناء عمل الفريق، ويُفتح نموذج التذكرة خارج ساعات العمل. ويعتمد هذا النمط على ساعات العمل المحددة في صندوق الوارد.
• التذاكر: بعد الإرسال يظهر رقم التذكرة، ومن «تذاكري» يرى العميل الحالة (مفتوحة، قيد المعالجة، بانتظار ردك، تم حلها، مغلقة) ويرد في المحادثة نفسها. وللاطلاع على الفرق بين التذاكر والدردشة، اقرأ «التذاكر مقابل الدردشة المباشرة» (Ticketing vs live chat).
• الاستبيان: بعد انتهاء المحادثة، وإذا كان استبيان القناة مفعّلًا، تظهر بطاقة تقييم من ١ إلى ٥ بالنمط المضبوط للقناة (وجوه تعبيرية أو نجوم أو أرقام). وإذا كانت النتيجة تهمك، فراجع ما هو CSAT.
• بعد انتهاء المحادثة: يعود العميل إلى الشاشة الأولى، ويمكنه بحسب نمط التواصل أن يفتح دردشة أو تذكرة جديدة.
• نموذج ما قبل الدردشة: إذا كان مفعّلًا للقناة، فيظهر قبل أول محادثة. راجع نموذج ما قبل الدردشة.

مسارات الشات بوت

تعمل مسارات الشات بوت محليًا في Android SDK دون أي شيفرة إضافية من جانبك. إذا كان في صندوق الوارد مسار نشط، يعرضه التطبيق في شاشة البداية: جميع أنواع العقد الـ17، والمتغيرات والشروط، والتحقق من الإدخال، والتقييم. يمكن تحويل الزائر إلى موظف مباشر أو كتذكرة، وتُسجَّل نفس تحليلات المسار التي يسجّلها ودجت الويب. إذا كان خيار require_flow مفعّلًا في المسار، تبقى بطاقة «بدء المحادثة» المباشرة مخفية ما دام المسار متاحًا (وتعود إذا تعذّر تحميله). تم فحص المحرك مقابل محرك الويب بـ40 سيناريو تكافؤ (نفس الخطوات والمتغيرات والأحداث)، وجرى التحقق من الشاشات على محاكي بالفارسية (من اليمين إلى اليسار) والإنجليزية. يُحرَّر المسار من لوحة التحكم فقط.

إعلانات وتحذيرات القناة

منذ 1.0.0-beta04 يعرض الـ SDK من تلقاء نفسه، ودون أي كود، الإعلانات التي أعددتها للقناة في اللوحة، وذلك في أعلى شاشة البداية في التطبيق. والإعدادات هي نفسها المستخدمة في أداة الويب (إعدادات القناة، قسم «Widget announcements»)؛ ولتعرف كيف تنشئها وتصوغ نصوصها اقرأ الإعلانات والتحذيرات في أداة الدردشة.

• أين تظهر: في أعلى الشاشة الرئيسية، وشاشة التذاكر حين تقوم مقام الشاشة الرئيسية، ونموذج ما قبل الدردشة، فوق مشغّل المسار وبطاقات البدء. ويأتي شريط تنبيه المشكلات بعدها.
• إعلانان على الأكثر، بمستويين: «إعلان» أصفر بأيقونة معلومات، و«تحذير» أحمر بأيقونة تحذير، في المظهرين الفاتح والداكن ومن اليمين إلى اليسار.
• النص والروابط: أجزاء بخط عريض وروابط على جزء من النص. لا تُفتح إلا العناوين http وhttps وmailto وtel، في التطبيق المناسب (المتصفح أو تطبيق الاتصال أو البريد) وليس داخل WebView أبدًا.
• الصورة: صورة https واحدة بوصف لـ TalkBack ورابط اختياري؛ وتُخفى إذا تعذّر تحميلها.
• الإغلاق: للإعلان القابل للإغلاق زر إغلاق، ويُحفظ اختيار المستخدم على ذلك الجهاز. وإذا غيّرت في اللوحة النص أو المستوى أو خيار «Visitors can close it» فإن الإعلان يظهر من جديد.
• الجدولة: لا يرسل الخادم إلا الإعلانات المفعّلة التي تقع ضمن نافذتها الزمنية؛ ولا يتولى الـ SDK شيئًا في هذا الشأن.
• الخوادم الأقدم: إذا لم تتوفر الميزة في الخادم، لا يظهر أي إعلان ويعمل بقية الـ SDK كالمعتاد.

وإذا بنيت واجهتك الخاصة، فالإعلانات التي لم تُغلق متاحة في StateFlow. أما HodhodChat وHodhod.open فيتولّيان ذلك بنفسيهما ولا يحتاجان إلى الكود التالي:

val items by Hodhod.repository.announcements.collectAsState()   // not closed yet, refreshed with the widget config

// e.g. from a close button of your own UI; ignored for announcements visitors cannot close
items.firstOrNull()?.let { Hodhod.repository.dismissAnnouncement(it.id) }

R8 وProGuard

تأتي القواعد المطلوبة داخل المكتبات نفسها (consumer-rules.pro)، فلا حاجة إلى إضافة شيء لإصدار release. وهي تحافظ على مُسلسِلات نماذج الـ SDK (serializers) وعلى HodhodChatActivity التي يبحث عنها Hodhod.open بالاسم. وإذا كانت لديك قاعدة للـ Activity أصلًا، فلا ضرر من تكرارها. وإذا فعّلت shrinkResources، فإن نصوص الـ SDK وخطوطه تُحفظ بملف keep المرفق معه.

استكشاف الأخطاء وإصلاحها

تعرض شاشة الدردشة خطأً أو لا تُحمَّل. اقرأ Hodhod.state؛ ففي حالة Failed تتضمن قيمة code:

• not_found: قيمة websiteToken أو baseUrl خاطئة.
• network: لا يستطيع الهاتف الوصول إلى الخادم.
• suspended: حساب هدهد معلّق.
• server: خطأ في الخادم؛ حاول مجددًا بعد قليل.
• cleartext: مرّرت عنوانًا يبدأ بـ http://.

لا يتصل الخادم المحلي (10.0.2.2). في المحاكي، يكون localhost جهازك هو 10.0.2.2. ولأن العنوان http://، تحتاج إلى أمرين، كلاهما لإصدارات debug فقط: مرّر allowCleartext = true في HodhodConfig، وفي ملف network_security_config الخاص بإصدار debug اسمح بحركة cleartext للعنوان 10.0.2.2 وحده (في التطبيق التجريبي المرفق مع الـ SDK مثال على ذلك). لا تستخدم أيًّا منهما في إصدارات release.

لا تصل الرسائل مباشرة، ويظهر شريط «لا يوجد اتصال». تعمل التحديثات المباشرة عبر WebSocket على المسار /cable. وقد يحجب وكيل (proxy) الشركة أو جدار الحماية أو شبكة CDN ترقية WebSocket. يعيد الـ SDK الاتصال بفاصل زمني متزايد؛ جرّب المسار نفسه على شبكة أخرى.

اللغة غير صحيحة. مرّر locale صراحةً في HodhodConfig. وبدونه تُستخدم لغة حساب هدهد (على الخادم)، ثم لغة الجهاز. وتُقبل رموز مثل fa-IR وتُختصر إلى fa.

يفشل identify. السبب غالبًا أن identifierHash خاطئ. تأكد من أنك استخدمت مفتاح HMAC الخاص بالقناة (لا websiteToken)، ومن أن identifier متطابق في التطبيق وفي الخادم الخلفي، ومن أن التجزئة مكتوبة بصيغة hex.

الأسئلة الشائعة