توزيع تطبيقات 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)، أضِف مكوّن 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
    }
  2. في ملف 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'
    }
  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 على المختبِرين، اتّبِع الخطوات التالية:

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. يمكنك العثور على رقم تعريف التطبيق في ملف 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

مجموعات المختبِرين التي تريد توزيع الإصدارات عليها (يمكنك الاطّلاع على إدارة المختبِرين). يتم تحديد المجموعات باستخدام الأسماء المستعارة للمجموعات، والتي يمكنك العثور عليها في علامة التبويب المختبِرون في وحدة تحكُّم App Distribution في 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 و 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
    
  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) و تثبيته مباشرةً. تنتهي صلاحية الرابط بعد ساعة واحدة.

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

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

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

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