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

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

قبل البدء

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

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

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

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

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

تتألف حزمة تطوير برامج Android لتوزيع التطبيقات من مكتبتَين:

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

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

يُرجى توضيح التبعية لحزمة تطوير البرامج (SDK) لنظام التشغيل 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-beta13")

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

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

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

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

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

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

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

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

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

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

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

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

    إذا كان الإصدار الجديد هو تطبيق Android PacKage (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.

انتقِل إلى دليل تحديد المشاكل وحلّها في ما يتعلّق بتوزيع التطبيقات للحصول على مساعدة بشأن المشاكل الشائعة، مثل:

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