إشعار المختبِرين بشأن الإصدارات الجديدة

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

قبل البدء

أضِف Firebase إلى مشروع Android، في حال لم يسبق لك إجراء ذلك.

الخطوة 1: تفعيل واجهة برمجة التطبيقات App Distribution Tester API

1. اختَر مشروعك في وحدة تحكّم Google Cloud.

2. ضمن Firebase App Testers API، انقر على تفعيل.

الخطوة 2: إضافة App Distribution إلى تطبيقك

تتكوّن حزمة App Distribution Android SDK من مكتبتَين:

• 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 لعرض مربّع حوار مُعدّ مسبقًا لتفعيل التنبيهات للمختبِرين الذين لم يفعّلوا التنبيهات بعد، ثم تحقّق مما إذا كان هناك إصدار جديد متاحًا. عند استدعاء الطريقة، تنفِّذ التسلسل التالي:

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

2. تبحث عن الإصدارات الجديدة المتاحة ليثبّتها المختبِر.

3. تعرِض تنبيهًا مُعدًّا مسبقًا يطلب من المختبِر إجراء التحديث.

4. إذا كان الإصدار الجديد عبارة عن حِزمة تطبيق Android (AAB)، تتم إعادة توجيه المختبِر إلى Google Play لإكمال عملية التحديث.

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

يمكنك استدعاء updateIfNewReleaseAvailable في أي وقت في تطبيقك. على سبيل المثال، يمكنك استدعاء updateIfNewReleaseAvailable أثناء onResume طريقة النشاط الرئيسي للتطبيق.

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

// 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.
          }
        }
      }
    }

// 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 للتحقّق مما إذا كان المختبِر يمكنه الوصول إلى إصدار جديد.

// 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.
    }
}

// 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():

firebaseAppDistribution.signInTester().addOnSuccessListener {
  // Handle successful sign-in.
}.addOnFailureListener {
  // Handle failed sign-in.
});

firebaseAppDistribution.signInTester().addOnSuccessListener( unused -> {
  // Handle successful sign-in.
}).addOnFailureListener(e -> {
  // Handle failed sign-in.
});

إعدادات التحديث المتقدّمة

تمنحك الطريقتان checkForNewRelease وupdateApp المزيد من المرونة في التخصيص عندما يُطلب من المختبِر إجراء التحديث. يمكنك أيضًا تخصيص مربّع حوار التحديث المُنشئ مسبقًا ومقياس مستوى التقدّم في التنزيل لكي يتوافقا بشكلٍ أفضل مع شكل تطبيقك وأسلوبه.

يُرجى العِلم أنّ updateApp لا يوفّر مؤشرًا لمستوى تقدّم عملية التنزيل. وهذا يعني أنّك بحاجة إلى تنفيذ إشارة التقدّم الخاصة بك باستخدام NotificationManager أو أي نوع من عرض الحالة داخل التطبيق أو أي أسلوب آخر.

يتحقّق المثال التالي ممّا إذا كان هناك إصدار جديد متوفّر، ثم يعرض واجهة مستخدم مخصّصة. قبل الاتصال بـ checkForNewRelease وupdateApp، تأكَّد من أنّ المختبِر سجّل الدخول باستخدام إعدادات تسجيل الدخول المتقدّمة.

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.
}

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():

firebaseAppDistribution.updateApp()
    .addOnProgressListener { updateState ->
      // Use updateState to show update progress.
    }

firebaseAppDistribution.updateApp()
    .addOnProgressListener(updateState -> {
      // Use updateState to show update progress.
    });

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

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

يُرجى الانتقال إلى App Distribution دليل تحديد المشاكل وحلّها للحصول على مساعدة بشأن المشاكل الشائعة، مثل:

• عدم تلقّي المختبِر تنبيهات داخل التطبيق
• يُطلب من المختبِر تسجيل الدخول إلى Google أكثر من مرة