تتيح لك حِزم SDK الاختيارية Firebase App Distribution لنظامَي التشغيل iOS وAndroid عرض تنبيهات داخل التطبيق للمختبِرين عندما تتوفّر إصدارات جديدة من تطبيقك ل التثبيت. يوضّح هذا الدليل كيفية استخدام App Distribution حِزم تطوير البرامج (SDK) لنظامَي التشغيل iOS وAndroid لإنشاء تنبيهات بشأن الإصدارات الجديدة وتخصيصها للمختبِرين.
قبل البدء
أضِف Firebase إلى مشروع Android، في حال لم يسبق لك إجراء ذلك.
الخطوة 1: تفعيل واجهة برمجة التطبيقات App Distribution Tester API
اختَر مشروعك في وحدة تحكّم Google Cloud.
ضمن Firebase App Testers API، انقر على تفعيل.
الخطوة 2: إضافة App Distribution إلى تطبيقك
تتكوّن حزمة SDK لنظام التشغيل App Distribution من مكتبتَين:
firebase-appdistribution-api
- مكتبة واجهة برمجة التطبيقات فقط، والتي يمكنك تضمينها في جميع صيغ الإصدار.firebase-appdistribution
- تنفيذ حزمة تطوير البرامج (SDK) بالكامل (اختياري)
تسمح المكتبة المخصّصة لواجهات برمجة التطبيقات فقط لرمزك البرمجي بإجراء طلبات بيانات من حزمة SDK. لن يكون للطلبات أثر إذا لم يكن تنفيذ حزمة SDK كاملاً.
حدِّد الاعتمادية لحزمة تطوير البرامج (SDK) لنظام التشغيل Android App Distribution في ملف Gradle الخاص بالوحدة
(على مستوى التطبيق) (عادةً <project>/<app-module>/build.gradle.kts
أو
<project>/<app-module>/build.gradle
). لتجنُّب تضمين وظيفة التحديث الذاتي لتنفيذ حزمة SDK الكاملة في إصدارات Play،
أضِف الاعتمادية على مكتبة واجهة برمجة التطبيقات فقط إلى جميع
صيغ الإصدار.
لا تُضِف عملية تنفيذ حزمة SDK الكاملة إلا إلى الصيغ المخصّصة فقط
لاختبار الإصدارات التجريبية.
dependencies {
// ADD the API-only library to all variants
implementation("com.google.firebase:firebase-appdistribution-api:16.0.0-beta14")
// ADD the full SDK implementation to the "beta" variant only (example)
betaImplementation("com.google.firebase:firebase-appdistribution:16.0.0-beta14")
}
هل تبحث عن وحدة مكتبة خاصة بلغة Kotlin؟ اعتبارًا من إصدار تشرين الأول (أكتوبر) 2023، يمكن لمطوّري Kotlin وJava الاعتماد على وحدة المكتبة الرئيسية (للاطّلاع على التفاصيل، يُرجى الاطّلاع على الأسئلة الشائعة حول هذه المبادرة).
الخطوة 3: ضبط التنبيهات داخل التطبيق
توفّر حزمة App Distribution Android SDK الطرق التالية لإعداد تنبيهات الإصدار داخل التطبيق للمختبِرين:
- إعداد تنبيه أساسي مزوّد بمربّعات حوار مُنشأة مسبقًا لتعديل التطبيق وتسجيل الدخول لعرضها على المختبِرين
- إعدادات تنبيهات متقدّمة تتيح لك تخصيص واجهة مستخدِم خاصة بك
إذا كنت تستخدم حزمة تطوير البرامج (SDK) لنظام التشغيل App Distribution Android للمرة الأولى، ننصحك باستخدامالإعداد الأساسي.
الإعدادات الأساسية
استخدِم updateIfNewReleaseAvailable
لعرض مربّع حوار مُعدّ مسبقًا لتفعيل التنبيهات
للمختبِرين الذين لم يفعّلوا التنبيهات بعد، ثم تحقّق مما إذا كان هناك إصدار
جديد متاحًا. عند استدعاء الطريقة، تنفِّذ التسلسل التالي:
يتحقّق من ما إذا كان المختبِر قد فعّل التنبيهات. إذا لم يُفعِّل المختبِر التنبيهات بعد، تطلب منه الطريقة تسجيل الدخول إلى App Distribution باستخدام حسابه على Google.
تبحث عن الإصدارات المتوفّرة حديثًا ليثبّتها المختبِر.
تعرِض تنبيهًا مُعدًّا مسبقًا يطلب من المختبِر إجراء التحديث.
إذا كان الإصدار الجديد عبارة عن حِزمة تطبيق Android (AAB)، تتم إعادة توجيه المختبِر إلى Google Play لإكمال عملية التحديث.
إذا كان الإصدار الجديد عبارة عن حزمة تطبيق Android (APK)، تنزِّل حزمة SDK الإصدار الجديد في الخلفية تطلب من المختبِر تثبيته عند اكتمال التنزيل. تُرسِل حزمة SDK إشعارات بشأن مستوى تقدّم التنزيل إلى المستخدم باستخدام
NotificationManager
. يمكنك أيضًا إضافة مؤشر التقدّم الخاص بك عن طريق إرفاق معالِجonProgressUpdate
بمهمّةupdateIfNewReleaseAvailable
.
يمكنك استدعاء updateIfNewReleaseAvailable
في أي وقت في تطبيقك. على سبيل المثال، يمكنك استدعاء updateIfNewReleaseAvailable
أثناء onResume
طريقة النشاط الرئيسي للتطبيق.
يتحقّق المثال التالي مما إذا كان المختبِر قد فعّل التنبيهات و يملك إذن الوصول إلى إصدار جديد. في حال استيفاء هذه الشروط، يتم عرض مربّع حوار عندما يصبح الإصدار متاحًا للتثبيت:
Kotlin+KTX
// Copy and paste this into any part of your app - for example, in your main
// activity's onResume method.
val firebaseAppDistribution = FirebaseAppDistribution.getInstance()
firebaseAppDistribution.updateIfNewReleaseAvailable()
.addOnProgressListener { updateProgress ->
// (Optional) Implement custom progress updates in addition to
// automatic NotificationManager updates.
}
.addOnFailureListener { e ->
// (Optional) Handle errors.
if (e is FirebaseAppDistributionException) {
when (e.errorCode) {
Status.NOT_IMPLEMENTED -> {
// SDK did nothing. This is expected when building for Play.
}
else -> {
// Handle other errors.
}
}
}
}
Java
// Copy and paste this into any part of your app - for example, in your main
// activity's onResume method.
FirebaseAppDistribution firebaseAppDistribution = FirebaseAppDistribution.getInstance();
firebaseAppDistribution.updateIfNewReleaseAvailable()
.addOnProgressListener(updateProgress -> {
// (Optional) Implement custom progress updates in addition to
// automatic NotificationManager updates.
})
.addOnFailureListener(e -> {
// (Optional) Handle errors.
if (e instanceof FirebaseAppDistributionException) {
switch (((FirebaseAppDistributionException)e).getErrorCode()) {
case NOT_IMPLEMENTED:
// SDK did nothing. This is expected when building for Play.
break;
default:
// Handle other errors.
break;
}
}
});
التهيئة المتقدمة
إعدادات تسجيل الدخول المتقدّمة
تمنحك الطريقتان signInTester
وisTesterSignedIn
مزيدًا من المرونة في
تخصيص تجربة تسجيل دخول المختبِر، لكي تتماشى تجربته مع شكل تطبيقك وأسلوبه بشكلٍ أفضل.
يتحقّق المثال التالي ممّا إذا كان المختبِر قد سجّل الدخول إلى حسابه في
App Distribution. يتيح لك ذلك اختيار عرض
واجهة مستخدم تسجيل الدخول (UI) للمختبِرين الذين لم يسجّلوا الدخول بعد فقط. بعد تسجيل دخول المختبِر، يمكنك الاتصال برقم updateIfNewReleaseAvailable
للتحقّق مما إذا كان المختبِر يمكنه الوصول إلى إصدار جديد.
Kotlin+KTX
// Only show sign-in UI if this is the "beta" variant (example).
if (BuildConfig.BUILD_TYPE == "beta" && !firebaseAppDistribution.isTesterSignedIn) {
// Start your sign-in UI here.
}
// Only check for updates if the tester is already signed in (do not prompt).
if (firebaseAppDistribution.isTesterSignedIn) {
firebaseAppDistribution.updateIfNewReleaseAvailable().addOnFailureListener {
// Handle failed update.
}
}
Java
// Only show sign-in UI if this is the "beta" variant (example).
if (BuildConfig.BUILD_TYPE == "beta" && !firebaseAppDistribution.isTesterSignedIn()) {
// Start your sign-in UI here.
}
// Only check for updates if the tester is already signed in (do not prompt).
if (firebaseAppDistribution.isTesterSignedIn()) {
firebaseAppDistribution.updateIfNewReleaseAvailable().addOnFailureListener( e -> {
// Handle failed update.
});
}
من واجهة مستخدم تسجيل الدخول، عندما يختار المختبِر المتابعة، اتصل signInTester()
:
Kotlin+KTX
firebaseAppDistribution.signInTester().addOnSuccessListener {
// Handle successful sign-in.
}.addOnFailureListener {
// Handle failed sign-in.
});
Java
firebaseAppDistribution.signInTester().addOnSuccessListener( unused -> {
// Handle successful sign-in.
}).addOnFailureListener(e -> {
// Handle failed sign-in.
});
إعدادات التحديث المتقدّمة
تمنحك الطريقتان checkForNewRelease
وupdateApp
المزيد من المرونة في
التخصيص عندما يُطلب من المختبِر إجراء التحديث. يمكنك أيضًا تخصيص
مربّع حوار التحديث المُنشئ مسبقًا ومقياس مستوى التقدّم في التنزيل لكي يتوافقا بشكلٍ أفضل مع شكل تطبيقك وأسلوبه.
يُرجى العِلم أنّ updateApp
لا يوفّر مؤشرًا لمستوى تقدّم عملية التنزيل. وهذا يعني
أنّك بحاجة إلى تنفيذ إشارة التقدّم الخاصة بك باستخدام
NotificationManager
أو أي نوع من عرض الحالة داخل التطبيق أو أي أسلوب
آخر.
يتحقّق المثال التالي ممّا إذا كان هناك إصدار جديد متوفّر، ثم يعرض
واجهة مستخدم مخصّصة. قبل الاتصال بـ checkForNewRelease
وupdateApp
، تأكَّد
من أنّ المختبِر سجّل الدخول باستخدام
إعدادات تسجيل الدخول المتقدّمة.
Kotlin+KTX
firebaseAppDistribution.checkForNewRelease().addOnSuccessListener { release ->
if (release != null) {
// New release available. Start your update UI here.
}
}.addOnFailureListener {
// Handle failed check for new release. Fails with Status#NOT_IMPLEMENTED
// if built for Play.
}
Java
firebaseAppDistribution.checkForNewRelease().addOnSuccessListener(release -> {
if (release != null) {
// New release available. Start your update UI here.
}
}).addOnFailureListener(e -> {
// Handle failed check for new release. Fails with Status#NOT_IMPLEMENTED
// if built for Play.
});
عندما يختار المختبِر مواصلة التحديث من واجهة مستخدم التحديث، اتصلupdateApp()
:
Kotlin+KTX
firebaseAppDistribution.updateApp()
.addOnProgressListener { updateState ->
// Use updateState to show update progress.
}
Java
firebaseAppDistribution.updateApp()
.addOnProgressListener(updateState -> {
// Use updateState to show update progress.
});
الخطوة 4: إنشاء عملية التنفيذ واختبارها
أنشئ تطبيقك واختَبِر عملية التنفيذ من خلال توزيع الإصدار على المختبِرين باستخدام وحدة تحكّم Firebase.
يُرجى الانتقال إلى App Distribution دليل تحديد المشاكل وحلّها للحصول على مساعدة بشأن المشاكل الشائعة، مثل:
- عدم تلقّي المختبِر تنبيهات داخل التطبيق
- يُطلب من المختبِر تسجيل الدخول إلى Google أكثر من مرة