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

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

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

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

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

• اكتشاف المشاكل المتعلّقة بأجهزة معيّنة وتصحيحها

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

• تقليل حجم عمليات التنزيل للمختبِرين

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

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

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

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

قبل البدء

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

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

2. افتح صفحة App Distribution في وحدة تحكّم Firebase. اختَر مشروع Firebase عندما يُطلب منك ذلك، ثم اختَر تطبيقك باستخدام التبديل بين التطبيقات، وانقر على البدء.

3. لإنشاء رابط Firebase يؤدي إلى Google Play وتحميل حِزمات تطبيق Android، تأكَّد من أنّ تطبيقك يستوفي المتطلبات التالية:

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

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

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

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

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

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

   3. اتّبِع التعليمات الظاهرة على الشاشة لتفعيل عملية دمج App Distribution واختَر تطبيقات Android على Firebase التي تريد ربطها بـ 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.5.0" apply false
   
       // Add the dependency for the App Distribution Gradle plugin
       id("com.google.firebase.appdistribution") version "5.3.1" 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.5.0' apply false
   
       // Add the dependency for the App Distribution Gradle plugin
       id 'com.google.firebase.appdistribution' version '5.3.1' apply false
   }

2. في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle)، أضِف المكوّن الإضافي App Distribution لنظام 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 التالية التي تتيح لأداة 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 على المختبِرين، اتّبِع التعليمات التالية:

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"
          }
      }
  }

  // ...
}

android {

  // ...

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

  // ...
}

يمكنك ضبط App Distribution لأنواع الإصدارات وصيغ المنتجات.

على سبيل المثال، لتوزيع إصدارات debug وrelease في نكهات المنتج "demo" و "full"، اتّبِع التعليمات التالية:

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"
          }
      }
  }

  // ...
}

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="1:1234567890:android:321abc456def7890"

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

testersFile="/path/to/testers.txt"

groups="qa-team, android-testers"

groupsFile="/path/to/tester-groups.txt"

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

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

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

الخطوة 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) ويثبّته مباشرةً تنتهي صلاحية الرابط بعد ساعة واحدة.

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

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

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

الخطوات التالية

• يمكنك تنفيذ الملاحظات داخل التطبيق لجمع الملاحظات من المختبِرين حول تطبيقك (بما في ذلك لقطات الشاشة).

• تعرَّف على كيفية عرض تنبيهات داخل التطبيق للمختبِرين عندما تتوفّر إصدارات جديدة من تطبيقك للتثبيت.

• انتقِل إلى الدرس التطبيقي حول ترميز مجموعة حزمات تطبيق Android للتعرّف على كيفية توزيع إصدارات حِزم التطبيقات خطوة بخطوة.

• تعرَّف على أفضل الممارسات لتوزيع تطبيقات Android على مختبِري تأكيد الجودة باستخدام CI/CD.