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

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

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

قبل البدء

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

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

الخطوة 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 = "APK"
              releaseNotesFile = "/path/to/releasenotes.txt"
              testers = "ali@example.com, bri@example.com, cal@example.com"
          }
      }
  }

  // ...
}

Groovy 

android {

  // ...

  buildTypes {
      release {
          firebaseAppDistribution {
              artifactType="APK"
              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 assembleRelease appDistributionUploadRelease

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

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

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

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

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

    • لدعوة مختبِرين إضافيين أو إزالة مختبِرين حاليين من مشروعك في 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 بجانب المختبِر في أحد الإصدارات. ويمكن تجديد الدعوة من خلال إعادة إرسالها باستخدام القائمة المنسدلة في صف المختبِر.

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