توزیع برنامه‌های 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 جستجو می‌کند.

مرحله ۳. «فایل سریع» خود را راه‌اندازی کنید و برنامه‌تان را توزیع کنید

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

   پارامترهای firebase_app_distribution
   app	الزامی: «شناسه برنامه Firebase» برنامه شما. می‌توانید «شناسه برنامه» را در کنسول 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

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

fastlane <lane>

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

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

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

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

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

(اختیاری) برای اینکه هر بار نسخه پخش جدیدی در «توزیع برنامه» ایجاد می‌کنید شماره ساخت به‌طور خودکار افزایش یابد، می‌توانید از کنش 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 آشنا شوید.