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


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

قبل البدء

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

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

  1. اختَر مشروعك في الـ Google Cloud console.

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

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

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

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

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

حدِّد الاعتمادية لحزمة تطوير البرامج (SDK) لنظام التشغيل Android في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً ما يكون <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle). لتجنُّب تضمين وظيفة التحديث الذاتي لحزمة تطوير البرامج (SDK) الكاملة في إصدارات Play، أضِف اعتمادية المكتبة التي تتضمّن واجهة برمجة التطبيقات فقط إلى جميع أشكال الإصدار.App Distribution أضِف حزمة تطوير البرامج (SDK) الكاملة إلى الأشكال المخصّصة حصريًا للاختبار قبل الإصدار.

dependencies {
    // ADD the API-only library to all variants
    implementation("com.google.firebase:firebase-appdistribution-api:16.0.0-beta18")

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

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

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

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