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

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

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

يتكامل توزيع التطبيقات مع خدمة مشاركة التطبيقات الداخلية في Google Play لمعالجة AABs التي تقوم بتحميلها وتقديم ملفات APK التي تم تحسينها لتكوينات أجهزة المختبرين لديك. يتيح لك توزيع AABs القيام بما يلي:

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

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

  • اختبار ميزات حزمة التطبيقات مثل Play Features Delivery و Play Asset Delivery .

  • تقليل حجم التنزيلات للمختبرين لديك.

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

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

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

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

الإجراء في وحدة تحكم Firebase مطلوب إذن IAM دور (أدوار) IAM التي تتضمن الأذونات المطلوبة بشكل افتراضي الأدوار الإضافية المطلوبة
ربط تطبيق Firebase بتطبيق في Google Play firebase.playLinks.update أحد الأدوار التالية: الوصول إلى حساب مطور Google Play كمسؤول
تحميل AABs لتوزيع التطبيق firebaseappdistro.releases.update أحد الأدوار التالية: ——

قبل ان تبدأ

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

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

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

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

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

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

  3. قم بربط تطبيق Firebase Android الخاص بك بحساب مطور Google Play الخاص بك:

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

    2. على بطاقة Google Play ، انقر فوق Link .
      إذا كانت لديك بالفعل روابط إلى 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.1" apply false
    
        // Add the dependency for the App Distribution Gradle plugin
        id("com.google.firebase.appdistribution") version "4.2.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.1' apply false
    
        // Add the dependency for the App Distribution Gradle plugin
        id 'com.google.firebase.appdistribution' version '4.2.0' 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 CLI في حالة عدم استخدام طريقة مصادقة أخرى.

الخطوة 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 لتطبيقك. مطلوب فقط إذا لم يكن البرنامج الإضافي Google Services Gradle مثبتًا لديك. يمكنك العثور على معرف التطبيق في ملف 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.

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

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 و appDistributionUpload BUILD-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 بجوار أداة الاختبار في الإصدار. يمكن تجديد الدعوة عن طريق إعادة إرسالها باستخدام القائمة المنسدلة في صف الاختبار.

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