توزيع تطبيقات Android على المختبِرين باستخدام Gradle

يمكنك دمج App Distribution في عملية إصدار Android باستخدام المكوّن الإضافي App Distribution Gradle. ويتيح لك المكوّن الإضافي تحديد المختبِرين وملاحظات الإصدار في ملف Gradle الخاص بتطبيقك، ما يتيح لك ضبط التوزيعات لأنواع الإصدارات والنُسخ المختلفة لتطبيقك.

يوضّح هذا الدليل كيفية توزيع مجموعات حزمات تطبيق Android (AAB) على المختبِرين باستخدام المكوّن الإضافي App Distribution Gradle.

تتكامل ميزة "توزيع التطبيقات" مع خدمة مشاركة التطبيقات الداخلية في Google Play لمعالجة ملفات AAB التي تحمّلها وعرض حِزم APK المحسَّنة لتتوافق مع إعدادات أجهزة المختبِرين. يتيح لك توزيع AAB إجراء ما يلي:

  • يمكنك تشغيل حِزم APK محسّنة (معروضة من خلال Google Play) تم تحسينها لتناسب أجهزة المختبِرين.

  • كشف المشاكل الخاصة بالجهاز وتصحيح الأخطاء فيها

  • اختبِر ميزات حِزم التطبيقات مثل عرض الميزات في Play وعرض المواد في Play.

  • يُرجى تقليل حجم المحتوى الذي يتم تنزيله للمختبِرين.

الأذونات المطلوبة

لتحميل ملفات AAB إلى ميزة App Distribution، يجب ربط تطبيق Firebase بتطبيق في Google Play. يجب أن يكون لديك مستوى الوصول المطلوب لتنفيذ هذه الإجراءات.

إذا لم يكن لديك إذن الوصول اللازم إلى Firebase، يمكنك أن تطلب من مالك مشروع Firebase منحك الدور المناسب من خلال إعدادات إدارة الهوية وإمكانية الوصول في وحدة تحكُّم Firebase. إذا كانت لديك أسئلة حول الوصول إلى مشروع Firebase، بما في ذلك البحث عن مالك أو تعيينه، راجع الأسئلة الشائعة حول"الأذونات وأذونات الوصول إلى مشاريع Firebase".

ينطبق الجدول التالي على ربط تطبيق Firebase بتطبيق في Google Play، بالإضافة إلى تحميل AAB.

الإجراء في وحدة تحكُّم Firebase الإذن المطلوب لإدارة الهوية وإمكانية الوصول أدوار "إدارة الهوية وإمكانية الوصول" التي تتضمّن الأذونات المطلوبة تلقائيًا الأدوار الإضافية المطلوبة
ربط تطبيق على Firebase بتطبيق في Google Play firebase.playLinks.update أحد الأدوار التالية: إذن الوصول إلى حساب مطوِّر على Google Play بصفتك مشرفًا
تحميل ملفات AAB إلى ميزة App Distribution firebaseappdistro.releases.update أحد الأدوار التالية: ––

قبل البدء

  1. أضِف Firebase إلى مشروع Android إذا لم يسبق لك إجراء ذلك. في نهاية سير العمل هذا، سيكون لديك تطبيق Firebase Android في مشروع Firebase.

    إذا كنت لا تستخدم أي منتجات أخرى من Firebase، ما عليك سوى إنشاء مشروع وتسجيل تطبيقك. وإذا قرّرت استخدام منتجات إضافية، احرص على إكمال جميع الخطوات الواردة في مقالة إضافة Firebase إلى مشروع Android.

  2. لإنشاء رابط Firebase إلى Google Play وتحميل ملفات AAB، تأكّد من أنّ تطبيقك يستوفي المتطلبات التالية:

    • تم تسجيل التطبيق في Google Play وتطبيق Firebase لنظام التشغيل Android باستخدام اسم الحزمة نفسه.

    • يتم إعداد التطبيق في Google Play من لوحة بيانات التطبيق ويتم توزيعه على إحدى قنوات Google Play (الاختبار الداخلي أو الاختبار المغلق أو الاختبار المفتوح أو قناة الإصدار العلني).

    • اكتملت مراجعة التطبيق في Google Play وتم نشره. يتم نشر تطبيقك إذا كان عمود حالة التطبيق يعرض إحدى الحالات التالية: الاختبار الداخلي (ليس اختبارًا داخليًا) أو الاختبار المغلق أو الاختبار المفتوح أو الإنتاج.

  3. اربط تطبيق Android على Firebase بحساب المطوِّر على Google Play:

    1. في "وحدة تحكُّم Firebase"، انتقِل إلى إعدادات المشروع، ثم اختَر علامة التبويب عمليات الدمج.

    2. في بطاقة Google Play، انقر على ربط.
      إذا كان لديك روابط تؤدي إلى Google Play، عليك النقر على إدارة بدلاً من ذلك.

    3. اتّبِع التعليمات الظاهرة على الشاشة لتفعيل عملية دمج App Distribution واختَر تطبيقات Firebase Android التي تريد ربطها بـ Google Play.

    مزيد من المعلومات عن الربط بخدمة Google Play

الخطوة 1. إعداد مشروع Android

  1. في ملف Gradle على مستوى الجذر (على مستوى المشروع) (<project>/build.gradle.kts أو <project>/build.gradle)، أضِف المكوّن الإضافي App Distribution Gradle كتبعية:

    Kotlin 

    plugins {
    // ...
    id("com.android.application") version "7.3.0" apply false

    // Make sure that you have the Google services Gradle plugin dependency
    id("com.google.gms.google-services") version "4.4.2" apply false

    // Add the dependency for the App Distribution Gradle plugin
    id("com.google.firebase.appdistribution") version "5.0.0" apply false
}

    Groovy 

    plugins {
    // ...
    id 'com.android.application' version '7.3.0' apply false

    // Make sure that you have the Google services Gradle plugin dependency
    id 'com.google.gms.google-services' version '4.4.2' apply false

    // Add the dependency for the App Distribution Gradle plugin
    id 'com.google.firebase.appdistribution' version '5.0.0' apply false
}

  2. في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle)، أضِف المكوّن الإضافي لنظام Gradle المخصَّص لميزة "توزيع التطبيقات":

    Kotlin 

    plugins {
  id("com.android.application")

  // Make sure that you have the Google services Gradle plugin
  id("com.google.gms.google-services")

  // Add the App Distribution Gradle plugin
  id("com.google.firebase.appdistribution")
}

    Groovy 

    plugins {
  id 'com.android.application'

  // Make sure that you have the Google services Gradle plugin
  id 'com.google.gms.google-services'

  // Add the App Distribution Gradle plugin
  id 'com.google.firebase.appdistribution'
}

  3. إذا كنت تستخدم جدار حماية أو خادم وكيل للشركة، أضِف موقع نظام Java التالي الذي يتيح لميزة "توزيع التطبيقات" تحميل التوزيعات إلى Firebase:

    -Djavax.net.ssl.trustStore=/path/to/truststore -Djavax.net.ssl.trustStorePassword=password

الخطوة 2. المصادقة باستخدام Firebase

قبل أن تتمكّن من استخدام مكوّن Gradle الإضافي، عليك أولاً المصادقة على مشروع Firebase بإحدى الطريقتين التاليتين. يبحث المكوّن الإضافي Gradle تلقائيًا عن بيانات الاعتماد من واجهة سطر الأوامر في Firebase في حال عدم استخدام طريقة مصادقة أخرى.

الخطوة 3. ضبط خصائص التوزيع

في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle)، اضبط ميزة "توزيع التطبيقات" من خلال إضافة قسم firebaseAppDistribution واحد على الأقل.

على سبيل المثال، لتوزيع إصدار release على المختبِرين، اتّبِع التعليمات التالية:

Kotlin 

import com.google.firebase.appdistribution.gradle.firebaseAppDistribution

android {

  // ...

  buildTypes {
      getByName("release") {
          firebaseAppDistribution {
              artifactType = "AAB"
              releaseNotesFile = "/path/to/releasenotes.txt"
              testers = "ali@example.com, bri@example.com, cal@example.com"
          }
      }
  }

  // ...
}

Groovy 

android {

  // ...

  buildTypes {
      release {
          firebaseAppDistribution {
              artifactType="AAB"
              releaseNotesFile="/path/to/releasenotes.txt"
              testers="ali@example.com, bri@example.com, cal@example.com"
          }
      }
  }

  // ...
}

يمكنك ضبط ميزة "توزيع التطبيقات" لأنواع الإصدارات ونكهات المنتجات.

على سبيل المثال، لتوزيع debug وrelease بنكهات منتجات "نسخة تجريبية" و "كاملة"، اتّبِع هذه التعليمات:

Kotlin 

import com.google.firebase.appdistribution.gradle.firebaseAppDistribution

android {

  // ...

  buildTypes {
      getByName("debug") {...}
      getByName("release") {...}
  }

  flavorDimensions += "version"
  productFlavors {
      create("demo") {
          dimension = "version"
          firebaseAppDistribution {
              releaseNotes = "Release notes for demo version"
              testers = "demo@testers.com"
          }
      }
      create("full") {
          dimension = "version"
          firebaseAppDistribution {
              releaseNotes = "Release notes for full version"
              testers = "full@testers.com"
          }
      }
  }

  // ...
}

Groovy 

android {

  // ...

  buildTypes {
      debug {...}
      release {...}
  }

  flavorDimensions "version"
  productFlavors {
      demo {
          dimension "version"
          firebaseAppDistribution {
              releaseNotes="Release notes for demo version"
              testers="demo@testers.com"
          }
      }
      full {
          dimension "version"
          firebaseAppDistribution {
              releaseNotes="Release notes for full version"
              testers="full@testers.com"
          }
      }
  }

  // ...
}

استخدِم المَعلمات التالية لضبط التوزيع:

معلمات إصدار توزيع التطبيقات
appId

رقم تعريف تطبيقك في Firebase. يكون هذا الحقل مطلوبًا فقط في حال لم يكن لديك مكوّن Gradle الإضافي لخدمات Google مثبّتًا. يمكنك العثور على رقم تعريف التطبيق في ملف google-services.json أو في "وحدة تحكّم Firebase" ضمن صفحة "الإعدادات العامة". تلغي القيمة في ملف build.gradle مخرجات القيمة من المكوِّن الإضافي google-services.

appId="1:1234567890:android:321abc456def7890"
serviceCredentialsFile

المسار إلى ملف JSON للمفتاح الخاص لحساب الخدمة. مطلوبة فقط في حال استخدام مصادقة حساب الخدمة.
artifactType

تُحدِّد نوع ملف تطبيقك. ويمكن ضبطها على "AAB" أو "APK".
artifactPath

المسار المطلق لملف APK أو AAB الذي تريد تحميله.
releaseNotes أو releaseNotesFile

ملاحظات الإصدار لهذا الإصدار

يمكنك تحديد ملاحظات الإصدار مباشرةً أو المسار إلى ملف نصي عادي.
testers أو testersFile

عناوين البريد الإلكتروني للمختبِرين الذين تريد توزيع الإصدارات عليهم.

يمكنك تحديد المختبِرين كقائمة مفصولة بفواصل من عناوين البريد الإلكتروني:

testers="ali@example.com, bri@example.com, cal@example.com"

يمكنك بدلاً من ذلك تحديد المسار إلى ملف يحتوي على قائمة بعناوين البريد الإلكتروني مفصولة بفواصل:

testersFile="/path/to/testers.txt"
groups أو groupsFile

مجموعات المختبِرين التي تريد توزيع الإصدارات عليها (يمكنك الاطّلاع على إدارة المختبِرين). يتم تحديد المجموعات باستخدام الأسماء المستعارة للمجموعات، والتي يمكنك العثور عليها في علامة التبويب المختبِرون في وحدة تحكُّم Firebase App Distribution.

يمكنك تحديد المجموعات كقائمة مفصولة بفواصل للأسماء المستعارة للمجموعات:

groups="qa-team, android-testers"

أو يمكنك تحديد المسار إلى ملف يحتوي على قائمة مفصولة بفواصل للأسماء المستعارة للمجموعات:

groupsFile="/path/to/tester-groups.txt"
testDevices أو testDevicesFile

تشكّل أنواع التوزيع التالية جزءًا من الميزة التجريبية للمختبِرين المبرمَجين.

الأجهزة الاختبارية التي تريد توزيع الإصدارات عليها (اطّلِع على الاختبارات الآلية).

يمكنك تحديد أجهزة الاختبار كقائمة مفصولة بفواصل منقوطة لمواصفات الجهاز:

testDevices="model=shiba,version=34,locale=en,orientation=portrait;model=b0q,version=33,locale=en,orientation=portrait"

يمكنك بدلاً من ذلك تحديد مسار ملف يحتوي على قائمة بمواصفات الجهاز مفصولة بفواصل منقوطة:

testDevicesFile="/path/to/testDevices.txt"
testUsername

اسم المستخدم لتسجيل الدخول التلقائي لاستخدامه أثناء الاختبارات الآلية.
testPassword أو testPasswordFile

كلمة مرور تسجيل الدخول التلقائي سيتم استخدامها أثناء الاختبارات الآلية.

أو يمكنك تحديد المسار إلى ملف نص عادي يحتوي على كلمة مرور:

testPasswordFile="/path/to/testPassword.txt"
testUsernameResource

اسم المورد لحقل اسم المستخدم لتسجيل الدخول تلقائيًا لاستخدامه أثناء الاختبارات الآلية.
testPasswordResource

اسم المورد لحقل كلمة المرور لتسجيل الدخول تلقائيًا، والذي سيتم استخدامه أثناء الاختبارات الآلية.
testNonBlocking

إجراء اختبارات مبرمجة بشكل غير متزامن انتقِل إلى "وحدة تحكُّم Firebase" للاطّلاع على نتائج الاختبار التلقائي.
stacktrace

طباعة جدول تسلسل استدعاء الدوال البرمجية لاستثناءات المستخدم. ويُعدّ هذا الإجراء مفيدًا عند تصحيح الأخطاء.

الخطوة 4. توزيع تطبيقك على المختبِرين

  1. أخيرًا، من أجل تجميع تطبيقك التجريبي ودعوة المختبِرين، أنشِئ الهدفَين BUILD-VARIANT و appDistributionUploadBUILD-VARIANT باستخدام برنامج تضمين Gradle لمشروعك، حيث تمثّل السمة BUILD-VARIANT صيغة المنتج الاختياري ونوع التصميم اللذين ضبطتهما في الخطوة السابقة. لمزيد من المعلومات حول نكهات المنتجات، يُرجى الاطّلاع على ضبط خيارات الإصدار.

    على سبيل المثال، لتوزيع تطبيقك باستخدام نسخة الإصدار release، يمكنك تشغيل الأمر التالي:

    ./gradlew bundleRelease appDistributionUploadRelease

    وإذا كنت قد أجريت المصادقة باستخدام حساب Google ولم تقدّم بيانات الاعتماد في ملف إصدار Gradle، يمكنك تضمين المتغيّر FIREBASE_TOKEN:

    export FIREBASE_TOKEN=1/a1b2c3d4e5f67890
./gradlew --stop // Only needed for environment variable changes
./gradlew bundleRelease appDistributionUploadRelease

  2. يمكنك أيضًا إلغاء القيم المحدّدة في ملف build.gradle من خلال تمرير وسيطات سطر الأوامر في شكل --<property-name>=<property-value>. على سبيل المثال:

    • لتحميل إصدار تصحيح الأخطاء إلى App Distribution، يُرجى اتّباع الخطوات التالية:

      ./gradlew bundleDebug appDistributionUploadDebug
    --artifactType="AAB"

    • لدعوة مختبِرين إضافيين أو إزالة مختبِرين حاليين من مشروعك في Firebase، عليك اتّباع الخطوات التالية:

      ./gradlew appDistributionAddTesters
    --projectNumber=<project_number>
    --emails="anothertester@email.com, moretesters@email.com"
./gradlew appDistributionRemoveTesters
    --projectNumber=<project_number>
    --emails="anothertester@email.com, moretesters@email.com"

      بعد إضافة مختبِر إلى مشروعك على Firebase، يمكنك إضافته إلى إصدارات فردية. لن يتمكن المختبِرون الذين تمت إزالتهم من الوصول إلى الإصدارات في مشروعك، ولكن قد يظل بإمكانهم الوصول إلى إصداراتك لفترة من الوقت.

    يمكنك أيضًا تحديد المختبِرين باستخدام --file="/path/to/testers.txt" بدلاً من --emails.

    تقبل المهمتان appDistributionAddTesters وappDistributionRemoveTesters أيضًا الوسيطات التالية:

    • projectNumber: رقم مشروع Firebase

    • serviceCredentialsFile: المسار إلى ملف بيانات اعتماد خدمة Google وهذه هي الوسيطة نفسها التي يستخدمها إجراء التحميل.

يعمل المكوّن الإضافي Gradle على إخراج الروابط التالية بعد تحميل الإصدار. تساعدك هذه الروابط في إدارة البرامج الثنائية والتأكد من أن المختبِرين والمطورين الآخرين لديهم الإصدار الصحيح:

  • firebase_console_uri: رابط إلى وحدة تحكُّم Firebase يعرض إصدارًا واحدًا يمكنك مشاركة هذا الرابط مع مطوّرين آخرين في مؤسستك.
  • testing_uri - رابط للإصدار في تجربة المختبِر (تطبيق Android الأصلي) يتيح للمختبِرين الاطّلاع على ملاحظات الإصدار وتثبيت التطبيق على أجهزتهم. يحتاج المختبِر إلى الوصول إلى الإصدار لاستخدام الرابط.
  • binary_download_uri - رابط موقَّع لتنزيل البرنامج الثنائي للتطبيق وتثبيته مباشرةً (ملف APK أو AAB). تنتهي صلاحية الرابط بعد ساعة واحدة.

بعد توزيع الإصدار، سيصبح متاحًا في لوحة بيانات "توزيع التطبيقات" ضمن وحدة تحكُّم Firebase لمدة 150 يومًا (خمسة أشهر). عندما تنتهي صلاحية الإصدار بعد 30 يومًا من انتهاء صلاحيته، يظهر إشعار انتهاء الصلاحية في كل من وحدة التحكّم وقائمة الإصدارات الخاصة بالمختبِرين على جهاز الاختبار.

يتلقّى المختبِرون الذين لم تتم دعوتهم لاختبار التطبيق دعوات بالبريد الإلكتروني لبدء الاستخدام، كما يتلقّى المختبِرون الحاليون إشعارات عبر البريد الإلكتروني تفيد بأنّ الإصدار الجديد جاهز لاختباره (اطّلِع على دليل إعداد المختبِر للحصول على تعليمات حول كيفية تثبيت التطبيق التجريبي). يمكنك مراقبة حالة كل مختبِر، وما إذا كان قد قبل الدعوة أم لا ونزَّل التطبيق في وحدة تحكُّم Firebase.

ويكون لدى المختبِرين 30 يومًا لقبول الدعوة لاختبار التطبيق قبل انتهاء صلاحيته. عندما تنتهي صلاحية الدعوة بعد 5 أيام من انتهاء صلاحيتها، يظهر إشعار انتهاء صلاحية في وحدة تحكُّم Firebase بجانب المختبِر في أحد الإصدارات. ويمكن تجديد الدعوة من خلال إعادة إرسالها باستخدام القائمة المنسدلة في صف المختبِر.

الخطوات اللاحقة