توزیع برنامه‌های Android برای آزمایش‌گران بااستفاده از Gradle

می‌توانید App Distribution را بااستفاده از افزایه Gradle App Distribution در فرایند ساخت Android خود ادغام کنید. این افزایه به شما امکان می‌دهد آزمایش‌کنندگان و یادداشت‌های انتشار را در فایل Gradle برنامه‌تان مشخص کنید و توزیع‌ها را برای انواع مختلف ساخت و گونه‌های برنامه‌تان پیکربندی کنید.

این راهنما نحوه توزیع «بسته‌های ترکیبی برنامه Android» ‏ (AAB) به آزمایش‌کنندگان را بااستفاده از افزایه App Distribution Gradle شرح می‌دهد.

App Distribution با سرویس هم‌رسانی برنامه داخلی Google Play ادغام می‌شود تا AABهایی را که بارگذاری می‌کنید پردازش کند و APKهایی را که برای پیکربندی‌های دستگاه آزمایش‌کنندگان شما بهینه‌سازی شده‌اند ارائه دهد. توزیع کردن «بسته‌های برنامه Android» به شما امکان می‌دهد کارهای زیر را انجام دهید:

• فایل‌های APK بهینه‌شده (ارائه‌شده توسط Google Play) را که برای دستگاه‌های آزمایش‌کنندگان شما بهینه‌سازی شده‌اند اجرا کنید.

• مشکلات مختص دستگاه را شناسایی و اشکال‌زدایی کنید.

• ویژگی‌های بسته برنامه را آزمایش کنید، مثل ویژگی تحویل Play و ارائه دارایی‌های Play.

• اندازه بارگیری‌ها را برای آزمایش‌کنندگان کاهش دهید.

مجوزهای لازم

برای بارگذاری کردن AAB در App Distribution، باید برنامه Firebase خود را به برنامه‌ای در Google Play پیوند دهید. برای انجام این کنش‌ها باید سطح دسترسی لازم را داشته باشید.

اگر دسترسی لازم به Firebase را ندارید، می‌توانید از «مالک» پروژه Firebase بخواهید بااستفاده از Firebase تنظیمات IAM کنسول، نقش مربوطه را به شما اختصاص دهد. اگر درباره دسترسی به پروژه Firebase خود سؤالی دارید، ازجمله پیدا کردن یا اختصاص دادن «مالک»، پرسشگان «اجازه‌ها و دسترسی به پروژه‌های Firebase» را مرور کنید.

جدول زیر برای پیوند دادن برنامه Firebase به برنامه در Google Play و همچنین بارگذاری AAB اعمال می‌شود.

قبل از شروع

1. اگر قبلاً این کار را نکرده‌اید، Firebase را به پروژه Android خود اضافه کنید. در پایان این گردش کار، یک «برنامه Android Firebase» در پروژه Firebase خود خواهید داشت.

   اگر از هیچ محصول Firebase دیگری استفاده نمی‌کنید، فقط باید پروژه‌ای ایجاد کنید و برنامه‌تان را ثبت کنید. اگر تصمیم گرفتید از محصولات دیگری استفاده کنید، حتماً همه مراحل افزودن Firebase به پروژه Android را تکمیل کنید.

2. صفحه App Distribution را در کنسول Firebase باز کنید. وقتی از شما خواسته شد، پروژه Firebase خود را انتخاب کنید، برنامه‌تان را بااستفاده از تعویض‌کننده برنامه انتخاب کنید، و روی شروع به کار کلیک کنید.

3. برای ایجاد پیوند Firebase به Google Play و بارگذاری کردن AAB، مطمئن شوید که برنامه‌تان الزامات زیر را برآورده می‌کند:

   • برنامه در Google Play و برنامه Android در Firebase هر دو بااستفاده از یک نام بسته ثبت شده‌اند.

   • برنامه در 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 بیشتر بدانید.

مرحله ۱. راه‌اندازی پروژه 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.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)، افزایه 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
   

مرحله ۲. اصالت‌سنجی با Firebase

قبل‌از اینکه بتوانید از افزونه Gradle استفاده کنید، ابتدا باید با یکی از روش‌های زیر در پروژه Firebase خود اصالت‌سنجی کنید. به‌طور پیش‌فرض، اگر از روش اصالت‌سنجی دیگری استفاده نشود، افزونه Gradle اعتبارنامه‌ها را از Firebase CLI جستجو می‌کند.

مرحله ۳. پیکربندی ویژگی‌های توزیع

در فایل 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 در نسخه‌های ویژه محصول «نمونه نمایشی» و «کامل»، این دستورالعمل‌ها را دنبال کنید:

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"

مرحله ۴. توزیع برنامه برای آزمایش‌کنندگان

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 دردسترس قرار می‌گیرد. وقتی ۳۰ روز به انقضای ساخت باقی مانده باشد، اعلان انقضا هم در کنسول و هم در فهرست ساخت‌های آزمایش‌کننده در دستگاه آزمایشی او نشان داده می‌شود.

آزمونگرانی که برای آزمایش برنامه دعوت نشده‌اند، دعوت‌نامه‌های ایمیلی برای شروع دریافت می‌کنند و آزمونگران فعلی اعلان‌های ایمیلی دریافت می‌کنند که ساخت جدیدی برای آزمایش آماده است (برای دستورالعمل‌های نحوه نصب برنامه آزمایشی، راهنمای راه‌اندازی آزمونگر را بخوانید). می‌توانید وضعیت هر آزمایش‌کننده را (اینکه دعوت را پذیرفته است یا نه و اینکه برنامه را بارگیری کرده است یا نه) در کنسول Firebase پایش کنید.

آزمونگران ۳۰ روز فرصت دارند تا دعوت آزمایش برنامه را قبل‌از منقضی شدن آن بپذیرند. وقتی ۵ روز به انقضای دعوت باقی مانده باشد، اعلان انقضا در کنسول Firebase در کنار آزمایش‌کننده در نسخه پخش ظاهر می‌شود. دعوت را می‌توان با ارسال مجدد آن بااستفاده از منوِ کرکره‌ای در ردیف آزمایش‌کننده تمدید کرد.

مراحل بعدی

• بازخورد درون‌برنامه‌ای را پیاده‌سازی کنید تا بازخورد آزمونگران را درباره برنامه‌تان (ازجمله نماگرفت‌ها) جمع‌آوری کنید.

• با نحوه نمایش هشدارهای درون‌برنامه به آزمونگران خود هنگام دردسترس بودن نسخه‌های ساخت جدید برنامه‌تان برای نصب آشنا شوید.

• برای آشنایی با نحوه توزیع گام‌به‌گام نسخه‌های پخش بسته برنامه، از codelab «بسته ترکیبی برنامه Android» بازدید کنید.

• با روال‌های مطلوب برای توزیع برنامه‌های Android بین آزمایش‌کنندگان تضمین کیفیت بااستفاده از CI/CD آشنا شوید.