توزيع تطبيقات Android على المختبِرين باستخدام Fastlane

يوضّح هذا المستند كيفية توزيع إصدارات حِزم APK على المختبِرين باستخدام fastlane، وهي منصة مفتوحة المصدر تعمل على إنشاء تطبيقات iOS وAndroid وإصدارها بشكل آلي. يتبع هذا المستند التعليمات المحددة في Fastfile. بعد إعداد fastlane وFastfile، يمكنك دمج App Distribution مع إعدادات fastlane.

قبل البدء

1. أضِف Firebase إلى مشروع Android الخاص بك، في حال لم يسبق لك إجراء ذلك.

   إذا لم تكن تستخدم أي منتجات أخرى من Firebase، ما عليك سوى إنشاء مشروع وتسجيل تطبيقك. ومع ذلك، إذا قررت استخدام منتجات إضافية في المستقبل، تأكَّد من إكمال جميع الخطوات الواردة في الصفحة المرتبطة أعلاه.

2. افتح صفحة App Distribution في وحدة تحكّم Firebase. اختَر مشروع Firebase عندما يُطلب منك ذلك، ثم اختَر تطبيقك باستخدام أداة التبديل بين التطبيقات، وانقر على البدء.

الخطوة 1: إعداد fastlane

1. تثبيت أداة fastlane وإعدادها

2. لإضافة App Distribution إلى إعدادات fastlane، نفِّذ الأمر التالي من جذر مشروع Android:

   fastlane add_plugin firebase_app_distribution

   إذا طلب منك الأمر تحديد خيار، اختَر Option 3: RubyGems.org.

الخطوة 2: المصادقة باستخدام Firebase

قبل أن تتمكّن من استخدام المكوّن الإضافي fastlane، عليك أولاً المصادقة باستخدام مشروع Firebase بإحدى الطرق التالية. يبحث المكوّن الإضافي fastlane تلقائيًا عن بيانات الاعتماد من واجهة سطر الأوامر في Firebase إذا لم يتم استخدام أي طريقة مصادقة أخرى.

الخطوة 3: إعداد ملف Fastfile وتوزيع تطبيقك

1. في مسار ./fastlane/Fastfile، أضِف مجموعة firebase_app_distribution. استخدِم المَعلمات التالية لضبط التوزيع:

   مَعلمات firebase_app_distribution
   app	مطلوب: رقم تعريف تطبيق Firebase الخاص بتطبيقك. يمكنك العثور على رقم تعريف التطبيق في وحدة تحكّم Firebase، ضمن صفحة الإعدادات العامة. app: "1:1234567890:android:0a1b2c3d4e5f67890"
   firebase_cli_token	رمز مميز لإعادة التحميل تتم طباعته عند مصادقة بيئة CI باستخدام واجهة سطر الأوامر (CLI) في Firebase (راجِع المقالة استخدام واجهة سطر الأوامر (CLI) مع أنظمة CI لمزيد من المعلومات).
   service_credentials_file	المسار إلى ملف json لحساب خدمة Google. اطّلِع أعلاه على كيفية المصادقة باستخدام بيانات اعتماد حساب الخدمة.
   android_artifact_type	يحدّد نوع ملف Android (حزمة APK أو حزمة تطبيق Android).
   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 API.

يُخرج المكوّن الإضافي fastlane الروابط التالية بعد تحميل الإصدار. تساعدك هذه الروابط في إدارة البرامج الثنائية والتأكّد من حصول المختبِرين والمطوّرين الآخرين على الإصدار الصحيح:

• رابط يؤدي إلى وحدة تحكّم Firebase يعرض إصدارًا واحدًا يمكنك مشاركة هذا الرابط مع مطوّرين آخرين في مؤسستك.
• رابط إلى الإصدار في تجربة المختبِر (تطبيق Android مدمج) يتيح للمختبِرين الاطّلاع على ملاحظات الإصدار وتثبيت التطبيق على أجهزتهم. ويجب أن يكون لدى المختبِر إذن الوصول إلى الإصدار ليتمكّن من استخدام الرابط.
• رابط موقَّع ينزّل ملف التطبيق الثنائي (ملف APK أو AAB) ويثبّته مباشرةً تنتهي صلاحية الرابط بعد ساعة واحدة.

بعد توزيع الإصدار، يصبح متاحًا في لوحة بيانات App Distribution في وحدة تحكّم Firebase لمدة 150 يومًا. عندما يتبقى 30 يومًا على انتهاء صلاحية الإصدار، يظهر إشعار بانتهاء الصلاحية في وحدة التحكّم وفي قائمة الإصدارات لدى المختبِر على جهازه الاختباري.

يتلقّى المختبِرون الذين لم تتم دعوتهم سابقًا لاختبار التطبيق دعوات عبر البريد الإلكتروني للبدء. يتلقّى المختبِرون الحاليون إشعارات عبر البريد الإلكتروني تفيد بأنّ إصدارًا جديدًا جاهز للاختبار. لمعرفة كيفية تثبيت التطبيق الاختباري، يُرجى الاطّلاع على دليل إعداد المختبِرين. يمكنك مراقبة حالة كل مختبِر لتحديد ما إذا كان قد قبل الدعوة وما إذا كان قد نزّل التطبيق في وحدة تحكّم 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"، يُرجى الاطّلاع على مقالة الحصول على معلومات عن أحدث إصدار من تطبيقك.

الخطوة 4 (اختيارية): إدارة المختبِرين لعملية التوزيع

يمكنك إضافة مختبِرين وإزالتهم من مشروعك أو مجموعتك باستخدام ملف 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: رمز المصادقة لواجهة سطر الأوامر (CLI) في Firebase

الوسيطتان service_credentials_file وfirebase_cli_token هما الوسيطتان نفسهما المستخدَمتان في إجراء التحميل.

الخطوة 5 (اختيارية): الحصول على معلومات عن أحدث إصدار من تطبيقك

يمكنك استخدام الإجراء firebase_app_distribution_get_latest_release لجلب معلومات عن أحدث إصدار من تطبيقك في App Distribution، بما في ذلك معلومات إصدار التطبيق وملاحظات الإصدار ووقت الإنشاء. وتشمل حالات الاستخدام زيادة الإصدار تلقائيًا ونقل ملاحظات الإصدار من الإصدار السابق.

قيمة العرض للإجراء هي تجزئة تمثّل أحدث إصدار. يتوفّر هذا التجزئة أيضًا باستخدام lane_context[SharedValues::FIREBASE_APP_DISTRO_LATEST_RELEASE]. لمزيد من المعلومات حول الحقول المتاحة في هذا التجزئة، يُرجى الاطّلاع على مستندات REST API.

المَعلمات

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

الخطوات التالية

• يمكنك تنفيذ الملاحظات داخل التطبيق لجمع الملاحظات من المختبِرين حول تطبيقك (بما في ذلك لقطات الشاشة).

• تعرَّف على كيفية عرض تنبيهات داخل التطبيق للمختبِرين عندما تتوفّر إصدارات جديدة من تطبيقك لتثبيتها.

• تعرَّف على أفضل الممارسات لتوزيع تطبيقات Android على مختبِري تأكيد الجودة باستخدام CI/CD.