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


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

قبل البدء

أضِف 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 طريقة النشاط الرئيسي للتطبيق.

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

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 أكثر من مرة