يمكنك دمج App Distribution في عملية إصدار Android باستخدام المكوّن الإضافي App Distribution Gradle. ويتيح لك المكوّن الإضافي تحديد المختبِرين وملاحظات الإصدار في ملف Gradle الخاص بتطبيقك، ما يتيح لك ضبط التوزيعات لأنواع الإصدارات والنُسخ المختلفة لتطبيقك.
يوضِّح هذا الدليل طريقة توزيع حِزم APK على المختبِرين باستخدام المكوّن الإضافي App Distribution Gradle.
قبل البدء
أضِف Firebase إلى مشروع Android إذا لم يسبق لك إجراء ذلك.
إذا كنت لا تستخدم أي منتجات أخرى من Firebase، عليك فقط إنشاء مشروع وتسجيل تطبيقك. أمّا إذا قرّرت استخدام منتجات إضافية في المستقبل، فاحرص على إكمال جميع الخطوات في الصفحة المُشار إليها أعلاه.
الخطوة 1. إعداد مشروع Android
في ملف 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 }
في ملف 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' }
إذا كنت تستخدم جدار حماية أو خادم وكيل للشركة، أضِف موقع نظام 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 مثبّتًا. يمكنك العثور على رقم تعريف التطبيق في
ملف appId="1:1234567890:android:321abc456def7890" |
serviceCredentialsFile
|
المسار إلى ملف JSON للمفتاح الخاص لحساب الخدمة. مطلوبة فقط في حال استخدام مصادقة حساب الخدمة. |
artifactType
|
تُحدِّد نوع ملف تطبيقك. ويمكن ضبطها على
|
artifactPath
|
المسار المطلق لملف APK أو AAB الذي تريد تحميله. |
releaseNotes أو releaseNotesFile |
ملاحظات الإصدار لهذا الإصدار يمكنك تحديد ملاحظات الإصدار مباشرةً أو المسار إلى ملف نصي عادي. |
testers أو testersFile |
عناوين البريد الإلكتروني للمختبِرين الذين تريد توزيع الإصدارات عليهم. يمكنك تحديد المختبِرين كقائمة مفصولة بفواصل من عناوين البريد الإلكتروني: testers="ali@example.com, bri@example.com, cal@example.com" يمكنك بدلاً من ذلك تحديد المسار إلى ملف يحتوي على قائمة بعناوين البريد الإلكتروني مفصولة بفواصل: testersFile="/path/to/testers.txt" |
groups أو groupsFile |
مجموعات المختبِرين التي تريد توزيع الإصدارات عليها (يمكنك الاطّلاع على
إدارة المختبِرين).
يتم تحديد المجموعات باستخدام يمكنك تحديد المجموعات كقائمة مفصولة بفواصل للأسماء المستعارة للمجموعات: 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. توزيع تطبيقك على المختبِرين
أخيرًا، من أجل تجميع تطبيقك التجريبي ودعوة المختبِرين، أنشِئ الهدفَين
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
يمكنك أيضًا إلغاء القيم المحدّدة في ملف
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
: رقم مشروع FirebaseserviceCredentialsFile
: المسار إلى ملف بيانات اعتماد خدمة Google وهذه هي الوسيطة نفسها التي يستخدمها إجراء التحميل.
يعمل المكوّن الإضافي Gradle على إخراج الروابط التالية بعد تحميل الإصدار. تساعدك هذه الروابط في إدارة البرامج الثنائية والتأكد من أن المختبِرين والمطورين الآخرين لديهم الإصدار الصحيح:
firebase_console_uri
: رابط إلى وحدة تحكُّم Firebase يعرض إصدارًا واحدًا يمكنك مشاركة هذا الرابط مع مطوّرين آخرين في مؤسستك.testing_uri
- رابط للإصدار في تجربة المختبِر (تطبيق Android الأصلي) يتيح للمختبِرين الاطّلاع على ملاحظات الإصدار وتثبيت التطبيق على أجهزتهم. يحتاج المختبِر إلى الوصول إلى الإصدار لاستخدام الرابط.binary_download_uri
- رابط موقَّع لتنزيل البرنامج الثنائي للتطبيق وتثبيته مباشرةً (ملف APK أو AAB). تنتهي صلاحية الرابط بعد ساعة واحدة.
بعد توزيع الإصدار، سيصبح متاحًا في لوحة بيانات "توزيع التطبيقات" ضمن وحدة تحكُّم Firebase لمدة 150 يومًا (خمسة أشهر). عندما تنتهي صلاحية الإصدار بعد 30 يومًا من انتهاء صلاحيته، يظهر إشعار انتهاء الصلاحية في كل من وحدة التحكّم وقائمة الإصدارات الخاصة بالمختبِرين على جهاز الاختبار.
يتلقّى المختبِرون الذين لم تتم دعوتهم لاختبار التطبيق دعوات بالبريد الإلكتروني لبدء الاستخدام، كما يتلقّى المختبِرون الحاليون إشعارات عبر البريد الإلكتروني تفيد بأنّ الإصدار الجديد جاهز لاختباره (اطّلِع على دليل إعداد المختبِر للحصول على تعليمات حول كيفية تثبيت التطبيق التجريبي). يمكنك مراقبة حالة كل مختبِر، وما إذا كان قد قبل الدعوة أم لا ونزَّل التطبيق في وحدة تحكُّم Firebase.
ويكون لدى المختبِرين 30 يومًا لقبول الدعوة لاختبار التطبيق قبل انتهاء صلاحيته. عندما تنتهي صلاحية الدعوة بعد 5 أيام من انتهاء صلاحيتها، يظهر إشعار انتهاء صلاحية في وحدة تحكُّم Firebase بجانب المختبِر في أحد الإصدارات. ويمكن تجديد الدعوة من خلال إعادة إرسالها باستخدام القائمة المنسدلة في صف المختبِر.
الخطوات اللاحقة
تنفيذ الملاحظات داخل التطبيق لتسهّل على المختبِرين إرسال الملاحظات والآراء حول تطبيقك (بما في ذلك لقطات الشاشة).
تعرَّف على كيفية عرض تنبيهات داخل التطبيق للمختبِرين عند توفُّر إصدارات جديدة من تطبيقك للتثبيت.
يمكنك الانتقال إلى الدرس التطبيقي حول ترميز "مجموعة حزمات تطبيق Android" للتعرّف على كيفية توزيع إصدارات حِزمة التطبيق خطوة بخطوة.
تعرَّف على أفضل الممارسات لتوزيع تطبيقات Android إلى مختبِري ضمان الجودة باستخدام CI/CD.