يمكنك دمج "App Distribution" في عملية تصميم Android باستخدام المكوّن الإضافي App Distribution Gradle. ويتيح لك المكوّن الإضافي تحديد المختبِرين وملاحظات الإصدار في ملف Gradle الخاص بتطبيقك، ما يتيح لك ضبط التوزيعات لأنواع الإصدارات والنُسخ المختلفة لتطبيقك.
يوضّح هذا الدليل كيفية توزيع حِزم APK على المختبِرين باستخدام ملف App Distribution Gradle الإضافي.
قبل البدء
أضِف Firebase إلى مشروع Android إذا لم يسبق لك إجراء ذلك.
إذا كنت لا تستخدم أي منتجات أخرى من Firebase، عليك فقط إنشاء مشروع وتسجيل تطبيقك. ومع ذلك، إذا قرّرت استخدام منتجات إضافية في المستقبل، احرص على إكمال جميع الخطوات في الصفحة المرتبطة أعلاه.
الخطوة 1: إعداد مشروع Android
في ملف Gradle على مستوى الجذر (على مستوى المشروع) (
<project>/build.gradle.kts
أو<project>/build.gradle
)، أضِف مكوّن Gradle الإضافي App Distribution كتبعية: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 الإضافي App Distribution: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 التالية التي تتيح لتطبيق App Distribution تحميل إصداراتك إلى 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
)، اضبط App Distribution من خلال إضافة قسم 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" } } } // ... }
يمكنك ضبط App Distribution لأجل أنواع الإصدارات ونُسخ المنتجات.
على سبيل المثال، لتوزيع إصدارَي 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" } } } // ... }
استخدِم المَعلمات التالية لضبط التوزيع:
مَعلمات الإصدار App Distribution | |
---|---|
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 wrapper في مشروعك، حيث يكون 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
: رقم مشروعك على Firebase.serviceCredentialsFile
: مسار ملف بيانات اعتماد خدمة Google وهذه هي الوسيطة نفسها التي يستخدمها إجراء التحميل.
يعمل المكوّن الإضافي Gradle على إخراج الروابط التالية بعد تحميل الإصدار. تساعدك هذه السلسلة من الخطوات في إدارة الملفات الثنائية والتأكّد من حصول المختبِرين والمطوّرين الآخرين على الإصدار الصحيح:
firebase_console_uri
: رابط إلى وحدة التحكّم Firebase يعرض إصدارًا واحدًا يمكنك مشاركة هذا الرابط مع مطوّرين آخرين في مؤسستك.testing_uri
- رابط للإصدار في تجربة المختبِر (تطبيق Android الأصلي) يتيح للمختبِرين الاطّلاع على ملاحظات الإصدار وتثبيت التطبيق على أجهزتهم. يحتاج المختبِر إلى إذن بالوصول إلى الإصدار لاستخدام الرابط.binary_download_uri
- رابط موقَّع يتيح تنزيل ملف التطبيق الثنائي (ملف APK أو حزمة AAB) و تثبيته مباشرةً. تنتهي صلاحية الرابط بعد ساعة واحدة.
بعد توزيع الإصدار، سيصبح متوفّرًا في لوحة بيانات "App Distribution" ضمن وحدة تحكُّم Firebase لمدة 150 يومًا (خمسة أشهر). عندما تنتهي صلاحية الإصدار بعد 30 يومًا من انتهاء صلاحيته، يظهر إشعار انتهاء الصلاحية في كل من وحدة التحكّم وقائمة الإصدارات الخاصة بالمختبِرين على جهاز الاختبار.
يتلقّى المختبِرون الذين لم تتم دعوتهم لاختبار التطبيق دعوات بالبريد الإلكتروني لبدء الاستخدام، كما يتلقّى المختبِرون الحاليون إشعارات عبر البريد الإلكتروني تفيد بأنّ الإصدار الجديد جاهز لاختباره (اطّلِع على دليل إعداد المختبِر للحصول على تعليمات حول كيفية تثبيت التطبيق التجريبي). يمكنك تتبُّع حالة كل مختبِر، وما إذا كان قد قبل الدعوة وما إذا كان قد نزّل التطبيق من خلال وحدة تحكّم "Firebase".
ويكون لدى المختبِرين 30 يومًا لقبول الدعوة لاختبار التطبيق قبل انتهاء صلاحيته. عندما تبقى 5 أيام على انتهاء صلاحية الدعوة، يظهر إشعار بانتهاء الصلاحية في وحدة تحكّم Firebase بجانب المختبِر في الإصدار. ويمكن تجديد الدعوة من خلال إعادة إرسالها باستخدام القائمة المنسدلة في صف المختبِر.
الخطوات التالية
تنفيذ الملاحظات داخل التطبيق لتسهِّل على المختبِرين إرسال الملاحظات والآراء حول تطبيقك (بما في ذلك لقطات الشاشة).
تعرَّف على كيفية عرض تنبيهات داخل التطبيق للمختبِرين عند توفُّر إصدارات جديدة من تطبيقك للتثبيت.
يمكنك الانتقال إلى الدرس التطبيقي حول ترميز "مجموعة حزمات تطبيق Android" للتعرّف على كيفية توزيع إصدارات حِزمة التطبيق خطوة بخطوة.
تعرَّف على أفضل الممارسات لتوزيع تطبيقات Android إلى مختبِري ضمان الجودة باستخدام CI/CD.