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

این راهنما نحوه توزیع ساخت‌های AAB به آزمایش‌کنندگان را بااستفاده از fastlane، پلاتفرم متن‌بازی که ساخت و انتشار برنامه‌های iOS و Android را خودکار می‌کند، شرح می‌دهد. این راهنما از دستورالعمل‌های تعریف‌شده در Fastfile پیروی می‌کند. پس‌از راه‌اندازی کردن برنامه‌ها. fastlane و Fastfile، می‌توانید App Distribution را با پیکربندی fastlane ادغام کنید.

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

مرحله ۱. راه‌اندازی fastlane

1. fastlane را نصب و راه‌اندازی کنید.

2. برای افزودن App Distribution به پیکربندی fastlane، فرمان زیر را از ریشه پروژه Android خود اجرا کنید:

   fastlane add_plugin firebase_app_distribution

   اگر فرمان گزینه‌ای را به شما پیشنهاد داد، Option 3: RubyGems.org را انتخاب کنید.

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

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

مرحله ۳. راه‌اندازی Fastfile و توزیع برنامه

1. در لاین ./fastlane/Fastfile، یک بلوک firebase_app_distribution اضافه کنید. از پارامترهای زیر برای پیکربندی توزیع استفاده کنید:

   پارامترهای firebase_app_distribution
   app	الزامی: شناسه Firebase App برنامه‌تان. می‌توانید «شناسه برنامه» را در کنسول Firebase، در صفحه تنظیمات کلی پیدا کنید. app: "1:1234567890:android:0a1b2c3d4e5f67890"
   firebase_cli_token	ژتون بازآوری که هنگام اصالت‌سنجی محیط CI با Firebase CLI چاپ می‌شود (برای اطلاعات بیشتر، استفاده از CLI با سیستم‌های CI را بخوانید).
   service_credentials_file	مسیر فایل json حساب سرویس Google شما. برای اطلاع از نحوه اصالت‌سنجی بااستفاده از اعتبارنامه‌های حساب سرویس، به بالا مراجعه کنید.
   android_artifact_type	نوع فایل Android (APK یا AAB) را مشخص می‌کند.
   android_artifact_path	جایگزین apk_path (منسوخ‌شده) می‌شود. مسیر مطلق به فایل APK یا AAB که می‌خواهید بارگذاری کنید. اگر مشخص نشده باشد، fastlane مکان فایل را از مسیری که فایل در آن تولید شده است تعیین می‌کند.
   release_notes release_notes_file	یادداشت‌های انتشار برای این ساخت. می‌توانید یادداشت‌های انتشار را مستقیماً مشخص کنید: release_notes: "Text of release notes" یا مسیر فایل نوشتار ساده را مشخص کنید: release_notes_file: "/path/to/release-notes.txt"
   testers testers_file	نشانی ایمیل آزمایش‌گرانی که می‌خواهید دعوت کنید. می‌توانید آزمایش‌گران را به‌صورت فهرست نشانی‌های ایمیل جداشده با کاما مشخص کنید: testers: "ali@example.com, bri@example.com, cal@example.com" یا می‌توانید مسیر فایل نوشتار ساده‌ای را مشخص کنید که حاوی فهرست نشانی‌های ایمیل جداشده با کاما است: testers_file: "/path/to/testers.txt"
   groups groups_file	گروه‌های آزمایش‌گری که می‌خواهید دعوت کنید (به مدیریت آزمایش‌گرها مراجعه کنید). گروه‌ها بااستفاده از نام‌های مستعار گروه مشخص می‌شوند که می‌توانید آن‌ها را در کنسول Firebase جستجو کنید. می‌توانید گروه‌ها را به‌صورت فهرستی جداشده با کاما مشخص کنید: groups: "qa-team, trusted-testers" یا می‌توانید مسیر فایل نوشتار ساده‌ای را مشخص کنید که حاوی فهرست جداشده با کاما از نام‌های گروه است: groups_file: "/path/to/groups.txt"
   test_devices test_devices_file	دستگاه‌های آزمایشی که می‌خواهید آزمایش‌های عامل آزمایش برنامه روی آن‌ها اجرا شود. می‌توانید دستگاه‌های آزمایشی را به‌صورت فهرستی از مشخصات دستگاه که با نقطه‌ویرگول از هم جدا شده‌اند مشخص کنید: test_devices: "model=shiba,version=34,locale=en,orientation=portrait" یا می‌توانید مسیر فایل نوشتار ساده‌ای را مشخص کنید که حاوی فهرست دستگاه‌های آزمایشی جداشده با نقطه‌ویرگول باشد: test_devices_file: "/path/to/test-devices.txt"
   test_username	نام کاربری برای ورود خودکار به سیستم که درطول آزمایش‌های عامل آزمایش برنامه استفاده می‌شود.
   test_password test_password_file	گذرواژه ورود خودکار به سیستم که درطول آزمایش‌های عامل آزمایش برنامه استفاده می‌شود. یا می‌توانید مسیر فایل نوشتار ساده حاوی گذرواژه را مشخص کنید: test_password_file: "/path/to/test-password.txt"
   test_username_resource	نام منبع برای فیلد نام کاربری برای ورود خودکار به سیستم که درطول آزمایش‌های عامل آزمایش برنامه استفاده می‌شود.
   test_password_resource	نام منبع برای فیلد گذرواژه برای ورود خودکار به سیستم که درطول آزمایش‌های عامل آزمایش برنامه استفاده می‌شود.
   test_non_blocking	اگر هنگام اجرای آزمایش‌های عامل آزمایش برنامه تنظیم شود، فرمان آزمایش‌ها را شروع می‌کند و سپس بلافاصله به‌جای منتظر ماندن برای تکمیل آن‌ها برمی‌گردد. برای دیدن نتایج آزمایش، به کنسول Firebase بروید. اگر این پرچم تنظیم نشده باشد، فرمان تا زمانی که آزمایش‌ها تکمیل نشوند مسدود خواهد شد و اگر هریک از آزمایش‌ها ناموفق باشد، با کد ناموفق خارج می‌شود.
   debug	پرچم بولی. می‌توانید این را روی true تنظیم کنید تا خروجی اشکال‌زدایی پرجزئیات چاپ شود.

platform :android do
    desc "My awesome app"
    lane :distribute do
        build_android_app(task: "bundle", ...)
        # build_android_app is a built-in fastlane action.
        release = firebase_app_distribution(
            app: "1:123456789:android:abcd1234",
            testers: "tester1@company.com, tester2@company.com",
            release_notes: "Lots of amazing new features to test out!",
            android_artifact_type: "AAB"
        )
    end
end

برای دردسترس قرار دادن ساخت برای آزمایش‌کنندگان، lane خود را اجرا کنید:

fastlane <lane>

مقدار بازگشتی کنش، درهم‌سازی است که نسخه پخش بارگذاری‌شده را نشان می‌دهد. این درهم‌سازی بااستفاده از lane_context[SharedValues::FIREBASE_APP_DISTRO_RELEASE] نیز دردسترس است. برای اطلاعات بیشتر درباره فیلدهای دردسترس در این درهم‌سازی، به سند REST API مراجعه کنید.

افزونه fastlane پس‌از بارگذاری نسخه پخش، پیوندهای زیر را خروجی می‌دهد. این پیوندها به شما کمک می‌کنند تا باینری‌ها را مدیریت کنید و مطمئن شوید که آزمایش‌کنندگان و توسعه‌دهندگان دیگر نسخه پخش مناسب را دارند:

• پیوندی به کنسول Firebase که یک انتشار را نمایش می‌دهد. می‌توانید این پیوند را با توسعه‌دهندگان دیگر در سازمانتان هم‌رسانی کنید.
• پیوندی به نسخه پخش در تجربه آزمایش‌کننده (برنامه Android داخلی) که به آزمایش‌کنندگان امکان می‌دهد یادداشت‌های انتشار را مشاهده کنند و برنامه را در دستگاهشان نصب کنند. آزمایش‌کننده برای استفاده از پیوند باید به نسخه پخش دسترسی داشته باشد.
• پیوند امضاشده‌ای که مستقیماً باینری برنامه (فایل APK یا AAB) را بارگیری و نصب می‌کند. پیوند پس‌از یک ساعت منقضی می‌شود.

پس‌از توزیع کردن ساخت، این ساخت به‌مدت ۱۵۰ روز در داشبورد App Distribution در کنسول Firebase دردسترس است. وقتی ۳۰ روز به انقضای نسخه ساخت باقی مانده باشد، اعلان انقضا در کنسول و در فهرست نسخه‌های ساخت آزمایش‌کننده در دستگاه آزمایشی او نشان داده می‌شود.

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

(اختیاری) برای افزایش خودکار شماره ساخت هر بار که نسخه جدیدی در App Distribution ایجاد می‌کنید، می‌توانید از کنش firebase_app_distribution_get_latest_release و، برای مثال، افزونه increment_version_code fastlane استفاده کنید. کد زیر مثالی از نحوه افزایش خودکار شماره ساخت ارائه می‌دهد:

lane :increment_version do
  latest_release = firebase_app_distribution_get_latest_release(
    app: "<your Firebase app ID>"
  )
  increment_version_code({ version_code: latest_release[:buildVersion].to_i + 1 })
end

برای کسب اطلاعات بیشتر درباره کنش firebase_app_distribution_get_latest_release، به دریافت اطلاعات درباره جدیدترین انتشار برنامه‌تان مراجعه کنید.

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

می‌توانید بااستفاده از فایل Fastfile یا با اجرای مستقیم کنش‌های fastlane، آزمایش‌کنندگان را به پروژه یا گروهتان اضافه یا از آن حذف کنید. اجرای مستقیم کنش‌ها مقادیر تنظیم‌شده در Fastfile را لغو می‌کند.

وقتی آزمایش‌کننده‌ای به پروژه Firebase شما اضافه شد، می‌توانید او را به نسخه‌های پخش تکی اضافه کنید. آزمایش‌گرانی که از پروژه Firebase شما برداشته می‌شوند دیگر به نسخه‌های پخش در پروژه شما دسترسی ندارند، اما ممکن است برای مدتی دسترسی به نسخه‌های پخش شما را حفظ کنند.

اگر تعداد زیادی آزمایش‌کننده دارید، بهتر است از گروه‌ها استفاده کنید.

استفاده از Fastfile

# Use lanes to add or remove testers from a project.
lane(:add_testers) do
  firebase_app_distribution_add_testers(
    emails: "foo@google.com,bar@google.com"
    # or file: "/path/to/testers.txt"
    group_alias: "qa-team" # (Optional) add testers to this group
  )
end

lane(:remove_testers) do
  firebase_app_distribution_remove_testers(
    emails: "foo@google.com,bar@google.com"
    # or file: "/path/to/testers.txt"
    group_alias: "qa-team" # (Optional) remove testers from this group only
  )
end

# Add or remove testers with the terminal
$ fastlane add_testers
$ fastlane remove_testers

اجرا کردن کنش‌های fastlane

fastlane run firebase_app_distribution_create_group display_name:"QA Team" alias:"qa-team"
fastlane run firebase_app_distribution_add_testers group_alias:"qa-team" emails:"foo@google.com,bar@google.com"
fastlane run firebase_app_distribution_remove_testers group_alias:"qa-team" emails:"foo@google.com,bar@google.com"
fastlane run firebase_app_distribution_delete_group alias:"qa-team"

همچنین می‌توانید آزمایش‌کنندگان را بااستفاده از --file="/path/to/testers.txt به‌جای --emails مشخص کنید.

تکالیف firebase_app_distribution_add_testers و firebase_app_distribution_remove_testers آرگومان‌های زیر را نیز می‌پذیرند:

• ‫project_number: شماره پروژه Firebase شما.
• group_alias (اختیاری): اگر مشخص شده باشد، آزمایش‌کنندگان به گروه مشخص‌شده اضافه (یا از آن برداشته) می‌شوند.
• ‫service_credentials_file: مسیر فایل اطلاعات کاربری سرویس Google شما.
• ‫firebase_cli_token: کد اصالت‌سنجی برای Firebase CLI.

‫service_credentials_file و firebase_cli_token همان آرگومان‌هایی هستند که کنش بارگذاری استفاده می‌کند.

مرحله ۵ (اختیاری). دریافت اطلاعات درباره جدیدترین نسخه پخش برنامه

می‌توانید از کنش firebase_app_distribution_get_latest_release برای واکشی اطلاعات مربوط به جدیدترین نسخه برنامه‌تان در «توزیع برنامه» استفاده کنید، ازجمله اطلاعات نسخه برنامه، یادداشت‌های انتشار، و زمان ایجاد. موارد استفاده شامل افزایش خودکار نسخه و انتقال یادداشت‌های انتشار از نسخه پخش قبلی است.

مقدار برگشتی کنش، درهم‌سازی است که جدیدترین نسخه پخش را نشان می‌دهد. این درهم‌سازی بااستفاده از lane_context[SharedValues::FIREBASE_APP_DISTRO_LATEST_RELEASE] نیز دردسترس است. برای اطلاعات بیشتر درباره فیلدهای دردسترس در این درهم‌سازی، به سند REST API مراجعه کنید.

پارامترها

app: "1:1234567890:android:0a1b2c3d4e5f67890"

مراحل بعدی

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

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

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