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


تتيح لك حِزم 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 الطرق التالية لإعداد تنبيهات الإصدار داخل التطبيق للمختبِرين:

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

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

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

استخدام updateIfNewReleaseAvailable لعرض تنبيهات تفعيل الإعدادات مسبقًا إلى المختبرين الذين لم يفعّلوا التنبيهات بعد، ثم تحقق مما إذا كانت إنشائه. عند استدعائها، تؤدي الطريقة التسلسل التالي:

  1. يتحقّق مما إذا كان أحد المختبِرين قد فعّل التنبيهات. في حال لم يفعّل المختبِر بعد للتنبيهات، تطلب الطريقة من المُختبِر تسجيل الدخول إلى App Distribution باستخدام حساباتهم على 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) يتيح لك هذا اختيار عرض تسجيل الدخول إلى واجهة المستخدم فقط للمختبِرين الذين لم يسجّلوا الدخول بعد. بعد تسجيل دخول المختبِر، يمكنك الاتصال بـ 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 أكثر من مرة.