مختبرِي التنبيهات بشأن إصدارات تطبيقك الجديدة من خلال حزمة تطوير البرامج (SDK) الخاصة بميزة "توزيع التطبيقات من Firebase" لنظام التشغيل Android - درس تطبيقي حول الترميز

1. نظرة عامة

مرحبًا بك في برنامج التدريب العملي حول دمج حزمة تطوير البرامج (SDK) لخدمة Firebase App Distribution في تطبيق Android. في هذا الدرس العملي، ستضيف حزمة تطوير البرامج (SDK) لنظام التشغيل Android الخاصة بميزة App Distribution إلى تطبيقك لعرض تنبيهات داخل التطبيق للمختبِرين عند توفّر إصدارات جديدة للتنزيل. ستتعرّف على كيفية استخدام كلّ من الإعدادات الأساسية والإعدادات المخصّصة لتسجيل دخول المختبِرين وتلقّي التحديثات. بعد ذلك، ستدفع إصدارًا جديدًا إلى App Distribution وسيتم إرسال تنبيه جديد بشأن الإصدار مباشرةً في التطبيق.

أهداف الدورة التعليمية

• كيفية استخدام App Distribution لتوزيع إصدار تجريبي من تطبيق على المختبِرين
• كيفية دمج حزمة تطوير البرامج (SDK) لنظام التشغيل Android في App Distribution في تطبيقك
• كيفية تنبيه أحد المختبِرين عند توفّر إصدار جديد من الإصدارات التجريبية قبل الإصدار جاهز للتثبيت
• كيفية تخصيص حزمة تطوير البرامج (SDK) لتناسب احتياجات الاختبار

المتطلبات

• أحدث إصدار من استوديو Android
• نموذج التعليمات البرمجية
• جهاز اختبار يعمل بالإصدار 4.4 من نظام التشغيل Android أو الإصدارات الأحدث ويتضمّن "خدمات Google Play" 9.8 أو الإصدارات الأحدث، أو محاكي يتضمّن "خدمات Google Play" 9.8 أو الإصدارات الأحدث
• إذا كنت تستخدم جهازًا، ستحتاج إلى كابل توصيل.

2. الحصول على الرمز النموذجي

استنسِخ مستودع GitHub من سطر الأوامر.

$ git clone https://github.com/FirebaseExtended/codelab-appdistribution-android.git

إذا لم يكن لديك git مثبّتًا، يمكنك أيضًا تنزيل نموذج المشروع من صفحة GitHub أو بالنقر على هذا الرابط.

3- استيراد التطبيق النموذجي

من "استوديو Android"، اختَر الدليل codelab-appdistribution-android/start ( ) من تنزيل نموذج الرمز البرمجي (ملف > فتح > .../codelab-appdistribution-android/start).

يجب أن يكون مشروع البدء مفتوحًا الآن في "استوديو Android".

4. إنشاء مشروع Firebase وإعداده

إنشاء مشروع جديد على Firebase

1. سجِّل الدخول إلى وحدة تحكّم Firebase باستخدام حسابك على Google.
2. انقر على الزر لإنشاء مشروع جديد، ثم أدخِل اسم المشروع (على سبيل المثال، App Distribution Codelab).
3. انقر على متابعة.
4. إذا طُلب منك ذلك، راجِع بنود Firebase واقبلها، ثم انقر على متابعة.
5. (اختياري) فعِّل ميزة "المساعدة المستندة إلى الذكاء الاصطناعي" في وحدة تحكّم Firebase (المعروفة باسم "Gemini في Firebase").
6. في هذا الدرس العملي، لا تحتاج إلى "إحصاءات Google"، لذا أوقِف خيار "إحصاءات Google".
7. انقر على إنشاء مشروع، وانتظِر إلى أن يتم توفير مشروعك، ثم انقر على متابعة.

إضافة تطبيق إلى Firebase

تسجيل تطبيقك في Firebase استخدِم "com.google.firebase.appdistributioncodelab" كاسم للحزمة.

إضافة ملف google-services.json إلى تطبيقك

بعد إضافة اسم الحزمة واختيار "تسجيل"، اتّبِع الخطوات التالية لإضافة ملف google-services.json إلى تطبيقك:

1. انقر على تنزيل ملف google-services.json للحصول على ملف إعداد Firebase Android.
2. انسخ ملف google-services.json إلى دليل app في مشروعك.
3. بعد تنزيل الملف، يمكنك تخطّي الخطوات التالية المعروضة في وحدة التحكّم (تم تنفيذها مسبقًا في مشروع build-android-start).

تعديل معرّف التطبيق ليتطابق مع تطبيقك على Firebase

1. في القائمة اليمنى (علامة تبويب "المشروع")، تأكَّد من أنّك في "طريقة العرض" Android، ثم ابحث عن علامة التبويب "برامج Gradle النصية" وافتح ملف Gradle للوحدة (على مستوى التطبيق) (عادةً app/build.gradle.kts).
2. غيِّر قيمة السمة applicationId لتتطابق مع معرّف تطبيقك على Firebase، والذي يجب أن يكون "com. google.firebase.appdistributioncodelab".

مزامنة مشروعك مع ملفات Gradle

لضمان توفّر جميع العناصر التابعة لتطبيقك، عليك مزامنة مشروعك مع ملفات Gradle من خلال اختيار ملف > مزامنة المشروع مع ملفات Gradle من شريط أدوات "استوديو Android".

5- إعداد تنبيهات بشأن الإصدارات الجديدة داخل التطبيق باستخدام حزمة تطوير البرامج (SDK) لنظام التشغيل Android في App Distribution

في هذه الخطوة، ستضيف حزمة تطوير البرامج (SDK) لنظام التشغيل Android في Firebase App Distribution إلى تطبيقك وستعرض تنبيهات داخل التطبيق للمختبِرين عند توفّر إصدارات جديدة من تطبيقك لتثبيتها. لإجراء ذلك، تأكَّد من تفعيل Firebase App Testers API لمشروع "Firebase Codelab" (في Google Cloud Console). عليك تسجيل الدخول باستخدام الحساب نفسه واختيار المشروع الصحيح من القائمة المنسدلة في أعلى الصفحة.

ضبط التنبيهات داخل التطبيق

توفّر حزمة تطوير البرامج (SDK) لنظام التشغيل Android في "توزيع التطبيقات" طريقتَين لإعداد تنبيهات الإصدار داخل التطبيق للمختبِرين:

• إعداد تنبيه أساسي يتضمّن مربّع حوار مُعدًّا مسبقًا لعرضه على المختبِرين
• إعداد تنبيه متقدّم يتيح لك تخصيص واجهة المستخدِم (UI)

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

1. تتحقّق هذه السمة ممّا إذا كان أحد المختبِرين قد فعّل التنبيهات. إذا لم يكن الأمر كذلك، تعرض الطريقة مربّع حوار مُعدًّا مسبقًا يطلب من المختبِرين تسجيل الدخول إلى "توزيع التطبيقات" باستخدام حساباتهم على Google.

تفعيل التنبيهات هو عملية تتم لمرة واحدة على الجهاز الاختباري وتستمر مع تحديثات تطبيقك. وتبقى التنبيهات مفعَّلة على الجهاز الاختباري إلى أن يتم إلغاء تثبيت التطبيق أو إلى أن يتم استدعاء الطريقة signOutTester.

2. البحث عن أحدث الإصدارات المتاحة للمختبِر لتثبيتها
3. تعرض هذه السمة تنبيهًا مُعدًّا مسبقًا يطلب من المختبِر تنزيل أحدث إصدار.
4. يتحقّق من نوع الإصدار الجديد قبل المتابعة في عملية التحديث:
5. إذا كان الإصدار الجديد عبارة عن حِزمة تطبيق (AAB)، تتم إعادة توجيه المختبِر إلى "متجر Play" لإكمال عملية التحديث.
6. إذا كان الإصدار الجديد عبارة عن حزمة APK، ستنزّل حزمة تطوير البرامج (SDK) الإصدار الجديد في الخلفية وتطلب من المختبِر تثبيته عند اكتمال التنزيل. ترسل حزمة SDK إشعارات بمدى تقدّم عملية التنزيل إلى المستخدم باستخدام NotificationManager.. يمكنك إضافة مؤشر تقدّم خاص بك عن طريق ربط معالج onProgressUpdate بمهمة updateIfNewReleaseAvailable.

يمكنك استدعاء updateIfNewReleaseAvailable() في أي نقطة في تطبيقك. على سبيل المثال، يمكنك استدعاء updateIfNewReleaseAvailable() أثناء طريقة onResume() في MainActivity:

افتح MainActivity.kt، وأنشئ طريقة onResume() على النحو التالي:

MainActivity.kt

override fun onResume() {
    super.onResume()
    checkForUpdate()
}

لننفّذ الآن الطريقة checkForUpdate().

MainActivity.kt

   private fun checkForUpdate() {
        firebaseAppDistribution.updateIfNewReleaseAvailable()
            .addOnProgressListener { updateProgress ->
                // (Optional) Implement custom progress updates in addition to
                // automatic NotificationManager updates.
            }
            .addOnFailureListener { e ->
                if (e is FirebaseAppDistributionException) {
                    // Handle exception.
                }
            }
    }

6. إنشاء تطبيق ودعوة مختبِرين لتنزيله

في هذه الخطوة، يمكنك إنشاء تطبيقك واختبار عملية التنفيذ من خلال توزيع الإصدار على المختبِرين باستخدام وحدة تحكّم Firebase.

إنشاء تطبيقك

عندما تكون مستعدًا لتوزيع إصدار تجريبي من تطبيقك على المختبِرين، أنشئ حِزمة APK باستخدام طريقتك العادية. يجب توقيع حزمة APK باستخدام مفتاح تصحيح الأخطاء أو مفتاح توقيع التطبيق.

توزيع تطبيقك على المختبِرين

لتوزيع تطبيقك على المختبِرين، حمِّل ملف APK باستخدام وحدة تحكّم Firebase:

1. افتح صفحة App Distribution في وحدة تحكّم Firebase. اختَر مشروعك على Firebase عند مطالبتك بذلك.
2. في صفحة "الإصدارات"، اختَر التطبيق الذي تريد توزيعه من القائمة المنسدلة.

3. انقر على البدء.

4. اسحب ملف APK الخاص بتطبيقك إلى وحدة التحكّم لتحميله.
5. عند اكتمال عملية التحميل، حدِّد مجموعات المختبِرين والمختبِرين الفرديين الذين تريد أن يتلقّوا الإصدار. (أضِف عنوان بريدك الإلكتروني لتلقّي الدعوة). بعد ذلك، أضِف ملاحظات الإصدار للنسخة. لمزيد من المعلومات عن إنشاء مجموعات المختبِرين، يمكنك الاطّلاع على مقالة إضافة مختبِرين وإزالتهم.

6. انقر على توزيع لإتاحة الإصدار للمختبِرين.

في وحدة تحكّم Firebase، يمكنك الآن الاطّلاع على المختبِرين الذين أضفتهم ضمن إصدار تطبيقك.

بما أنّك أدرجت عنوان بريدك الإلكتروني، ستتلقّى رسالة إلكترونية من Firebase App Distribution تدعوك إلى اختبار التطبيق. أنت الآن أول مختبِر. اتّبِع التعليمات الواردة في مقالة قبول الدعوة لإعداد حسابك كمختبِر على جهازك الاختباري.

قبول الدعوة

يجب أولاً قبول الدعوة لتنزيل الإصدار واختباره.

1. على جهاز Android التجريبي، افتح الرسالة الإلكترونية المُرسَلة من Firebase App Distribution وانقر على البدء.
2. في تطبيق الويب الخاص بالمختبِرين Firebase App Distribution الذي يظهر، سجِّل الدخول باستخدام حسابك على Google وانقر على قبول الدعوة. يمكنك الآن الاطّلاع على الإصدار الذي تمت دعوتك لاختباره.

تنزيل الإصدار من الجهاز الاختباري

عند الانتقال إلى تطبيق codelab في App Distribution، يمكنك الاطّلاع على أنّ الإصدار جاهز للتنزيل.

1. انقر على تنزيل، ثم ثبِّت التطبيق وشغِّله.
2. عند بدء تشغيل التطبيق، سيطلب منك تفعيل تنبيهات الإصدارات الجديدة. انقر على تفعيل.

3. سجِّل الدخول باستخدام حسابك التجريبي.

سيتم إرجاعك إلى التطبيق، ولن تحتاج إلى تسجيل الدخول أو قبول التنبيهات في المرة التالية التي تشغّل فيها التطبيق.

توزيع تحديث على المختبِرين

1. عدِّل versionName إلى "1.1" وversionCode إلى 2 في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً app/build.gradle).
2. أنشئ حِزمة APK باستخدام العملية المعتادة. يجب توقيع حزمة APK باستخدام مفتاح تصحيح الأخطاء أو مفتاح توقيع التطبيق.
3. حمِّل حِزمة APK الجديدة هذه في وحدة تحكّم Firebase، وأضِف عنوان بريدك الإلكتروني كمختبِر مرة أخرى، ثم انقر على توزيع.

تنبيهات الإصدار التجريبي

1. تأكَّد من إغلاق التطبيق إذا كان مفتوحًا.
2. أعِد تشغيل التطبيق.
3. عند إعادة تشغيل التطبيق، ستتلقّى تنبيهًا بعنوان "يتوفّر إصدار جديد".

4. لتلقّي أحدث إصدار، انقر على تحديث.
5. إذا طُلب منك ذلك، اختَر خيار تفعيل عمليات التثبيت من مصادر غير معروفة.
6. انقر على تثبيت (أو تحديث) في الشاشة التالية.

7. تهانينا! تمكّنت من تعديل تطبيقك باستخدام التنبيهات المضمّنة.

7. تخصيص عملية تسجيل الدخول للمختبِرين

تمنحك الطريقتان signInTester/signOutTester وisTesterSignedIn مرونة أكبر في تخصيص تجربة تسجيل الدخول للمختبِر، ما يتيح لك مطابقة شكل تطبيقك وأسلوبه بشكل أفضل.

يتحقّق المثال التالي ممّا إذا كان المختبِر قد سجّل الدخول إلى حساب المختبِر على Firebase App Distribution، حتى تتمكّن من اختيار عرض واجهة مستخدم تسجيل الدخول للمختبِرين الذين لم يسجّلوا الدخول بعد. بعد أن يسجّل المختبِر الدخول، يمكنك بعد ذلك استدعاء checkForUpdate للتحقّق مما إذا كان بإمكان المختبِر الوصول إلى إصدار جديد.

لنوقِف البحث عن التحديثات تلقائيًا في onResume من خلال إضافة تعليق إلى استدعاء checkForUpdate().

MainActivity.kt

override fun onResume() {
        super.onResume()
        //checkForupdate()
    }

بدلاً من ذلك، تمت إضافة checkForUpdate() إلى OnClickListener الخاص بـ updatebutton.

لننفّذ الآن طريقة signIn() التي ستسجّل دخول المستخدم إذا كان قد سجّل خروجه، أو ستسجّل خروجه إذا كان قد سجّل دخوله.

MainActivity.kt

    private fun signIn() {
        if (isTesterSignedIn()) {
            firebaseAppDistribution.signOutTester()
            configureUpdateButton()
            configureSigninButton()
        } else {
            firebaseAppDistribution.signInTester()
        }
    }

أخيرًا، لننفِّذ الطريقة isTesterSignedIn.

MainActivity.kt

    private fun isTesterSignedIn() : Boolean {
        return firebaseAppDistribution.isTesterSignedIn
    }

إنشاء عملية التنفيذ واختبارها

8. تهانينا!

لقد أنشأت ميزة "عرض التنبيهات داخل التطبيق" في أحد التطبيقات باستخدام حزمة تطوير البرامج (SDK) لنظام التشغيل Android في "توزيع التطبيقات على Firebase".

المواضيع التي تناولناها

• Firebase App Distribution
• ‫Firebase App Distribution New Alerts Android SDK

الخطوات التالية

• استخدام المكوّن الإضافي Fastlane
• استخدام أدوات واجهة سطر الأوامر
• استخدام Gradle

مزيد من المعلومات

• Firebase.google.com

هل لديك أي أسئلة؟

• ‫Stackoverflow‏ ‘firebase-app-distribution'
• قناة Slack الخاصة بمنتدى Firebase‏ ‎ #app-distribution

الإبلاغ عن مشاكل

• المشاكل في Github