تطبيق Android
دليل المطوّر لـ Android
يغطي هذا المستند تطبيق Android الأصلي الخاص بـ LeadHub — المكتوب بلغة Kotlin — الذي يتصل بنسختك من LeadHub عبر واجهة برمجة التطبيقات REST. يُوجَّه هذا الدليل للمطورين الذين يحتاجون إلى بناء التطبيق أو تخصيصه أو نشره.
المتطلبات
قبل البدء، تأكد من توفر ما يلي:
| المتطلب | التفاصيل |
|---|---|
| Android Studio | Hedgehog (2023.1.1) أو أحدث |
| JDK | 17 أو أعلى |
| الحد الأدنى لمستوى API | 26 (Android 8.0) |
| نسخة LeadHub | يجب أن تكون متاحة عبر HTTPS مع شهادة SSL صالحة |
| مفتاح API | يُنشأ من لوحة تحكم المستخدم |
إعداد المشروع
1. فتح المشروع
افتح مجلد android/ في Android Studio. سيقوم Gradle بمزامنة التبعيات تلقائيًا.
2. تكوين عنوان URL الأساسي
افتح app/src/main/assets/config.xml وحدد عنوان URL لنسختك:
<config>
<base_url>https://yourdomain.com</base_url>
</config>
3. المزامنة والبناء
نفّذ Build → Make Project للتحقق من أن كل شيء يُترجَم بشكل صحيح.
البنية المعمارية
يستخدم التطبيق نمط MVVM القياسي في Android:
| الطبقة | التقنية |
|---|---|
| الشبكة | Retrofit + OkHttp |
| حالة واجهة المستخدم | ViewModel + LiveData |
| التخزين المحلي | Room (قاعدة بيانات SQLite) |
| الإشعارات الفورية | Firebase Cloud Messaging (FCM) |
| تخزين بي انات الاعتماد | EncryptedSharedPreferences |
تدفق المصادقة
- يُدخل المستخدم عنوان URL للنسخة ومفتاح API في شاشة تسجيل الدخول.
- يستدعي التطبيق
GET /api/healthللتحقق من إمكانية الوصول إلى النسخة. - يستدعي التطبيق
GET /api/users/meباستخدام مفتاح API كرمز Bearer. - عند النجاح، يُحفظ مفتاح API في EncryptedSharedPreferences ويُعتبر المستخدم مصادَقًا.
الإشعارات الفورية
يستخدم التطبيق Firebase Cloud Messaging لإشعارات العملاء المحتملين الجدد.
- أنشئ مشروعًا في Firebase Console.
- أضف تطبيق Android باسم الحزمة الخاص بتطبيقك.
- قم بتنزيل
google-services.jsonوضعه في مجلدapp/. - أضف مفتاح خادم FCM (
FCM_SERVER_KEY) إلى تكوين خادم LeadHub حتى يتمكن الخادم من إرسال الإشعارات.
البناء للإصدار
1. إنشاء Keystore
keytool -genkey -v -keystore leadhub.keystore -alias leadhub -keyalg RSA -keysize 2048 -validity 10000
2. تكوين التوقيع
أضف تفاصيل keystore إلى ملف build.gradle الخاص بتطبيقك ضمن قسم signingConfigs.
3. بناء APK / AAB للإصدار
استخدم Build → Generate Signed Bundle / APK في Android Studio، أو نفّذ:
./gradlew bundleRelease
سيكون ملف AAB الناتج في app/build/outputs/bundle/release/.
4. الرفع إلى Google Play
ارفع ملف AAB في Google Play Console ضمن الإنتاج → إنشاء إصدار جديد.
نقاط نهاية API المستخدمة
| نقطة النهاية | الغرض |
|---|---|
GET /api/health | التحقق من إمكانية الوصول إلى النسخة |
GET /api/users/me | التحقق من صلاحية مفتاح API والحصول على معلومات المستخدم |
GET /api/leads | جلب قائمة العملاء المحتملين |
GET /api/leads/{id} | الحصول على تفاصيل عميل محتمل |
PUT /api/leads/{id} | تحديث عميل محتمل |
GET /api/pipelines | جلب خطوط الأنابيب والمراحل |
الحد الأدنى من صلاحيات مفتاح API المطلوبة
| الصلاحية | السبب |
|---|---|
read:leads | عرض العملاء المحتملين |
write:leads | تحديث العملاء المحتملين من التطبيق |
read:pipelines | عرض مراحل خط الأنابيب |