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


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

قبل البدء

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

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

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

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

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

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

تتكوّن حزمة تطوير البرامج (SDK) لنظام التشغيل Android من App Distribution من مكتبتَين:

  • firebase-appdistribution-api: مكتبة واجهة برمجة التطبيقات فقط، والتي يمكنك تضمينها في جميع تنويعات التصميم.
  • firebase-appdistribution - التنفيذ الكامل لحزمة تطوير البرامج (SDK) (اختياري)

تتيح المكتبة المخصّصة لواجهة برمجة التطبيقات فقط للرمز البرمجي إرسال طلبات إلى حزمة تطوير البرامج (SDK). ولن يكون لهذه الطلبات أي تأثير إذا لم يتم تنفيذ حزمة تطوير البرامج (SDK) بالكامل.

حدِّد الاعتمادية لحزمة تطوير البرامج (SDK) الخاصة بـ "App Distribution" على Android في ملف 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-beta21")

    // ADD the full SDK implementation to the "beta" variant only (example)
    betaImplementation("com.google.firebase:firebase-appdistribution:16.0.0-beta21")
}

هل تبحث عن وحدة مكتبة خاصة بلغة Kotlin؟ بدءًا من إصدار أكتوبر 2023، يمكن لمطوّري Kotlin وJava الاعتماد على وحدة المكتبة الرئيسية (لمعرفة التفاصيل، يُرجى الاطّلاع على الأسئلة الشائعة حول هذه المبادرة).

الخطوة 3: ضبط التنبيهات داخل التطبيق

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

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

إذا كنت تستخدم حزمة تطوير البرامج (SDK) لنظام التشغيل Android من "App Distribution" للمرة الأولى، ننصحك باستخدام الإعدادات الأساسية.

الإعدادات الأساسية

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

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

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

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

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

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

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

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

Kotlin 

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

Kotlin 

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

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 

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 

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