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


تتيح لك حِزم تطوير البرامج (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 إلى تطبيقك

تتكوّن حزمة تطوير البرامج (SDK) لنظام التشغيل Android 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-beta16")

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

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

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

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

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

إذا كنت تستخدم App Distribution Android SDK للمرة الأولى، ننصحك باستخدام الإعداد الأساسي.

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

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

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

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

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

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

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

يمكنك استدعاء 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 أكثر من مرة