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

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

قبل از اینکه شروع کنی

اگر هنوز Firebase را به پروژه اندروید خود اضافه نکرده‌اید، آن را اضافه کنید.

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

مرحله ۱. راه‌اندازی فست‌لین

1. نصب و راه‌اندازی فست‌لین

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

   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 شما. می‌توانید شناسه برنامه را در کنسول Firebase ، در صفحه تنظیمات عمومی پیدا کنید. app: "1:1234567890:android:0a1b2c3d4e5f67890"
   firebase_cli_token	یک توکن به‌روزرسانی که هنگام احراز هویت محیط CI خود با Firebase CLI چاپ می‌شود (برای اطلاعات بیشتر، بخش «استفاده از CLI با سیستم‌های CI» را بخوانید).
   service_credentials_file	مسیر فایل json حساب سرویس گوگل شما. برای نحوه احراز هویت با استفاده از اعتبارنامه‌های حساب سرویس ، به بالا مراجعه کنید.
   android_artifact_type	نوع فایل اندروید (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;model=b0q,version=33,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 API مراجعه کنید.

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

• لینکی به کنسول Firebase که یک نسخه واحد را نمایش می‌دهد. می‌توانید این لینک را با سایر توسعه‌دهندگان در سازمان خود به اشتراک بگذارید.
• لینکی به نسخه منتشر شده در محیط تست (اپلیکیشن اندروید) که به تسترها اجازه می‌دهد یادداشت‌های انتشار را مشاهده کرده و اپلیکیشن را روی دستگاه خود نصب کنند. تستر برای استفاده از لینک، نیاز به دسترسی به نسخه منتشر شده دارد.
• یک لینک امضا شده که مستقیماً فایل باینری برنامه (فایل 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 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"

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

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

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

فایل service_credentials_file و فایل firebase_cli_token همان آرگومان‌هایی هستند که توسط عمل آپلود استفاده می‌شوند.

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

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

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

پارامترها

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

مراحل بعدی

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

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

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