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

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

قبل از شروع

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

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

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

مرحله ۱. راه‌اندازی 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(...)
        # 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!"
        )
    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 آشنا شوید.