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

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

قبل البدء

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

إذا كنت لا تستخدم أي منتجات أخرى من 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 باستخدام واجهة سطر الأوامر Firebase (يمكنك الاطّلاع على استخدام واجهة سطر الأوامر مع أنظمة 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;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 تعرض إصدارًا واحدًا. يمكنك مشاركة هذا الرابط مع مطوّرين آخرين في مؤسستك.
• رابط يؤدي إلى الإصدار في تجربة المختبِر (تطبيق 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_name: رقم مشروعك على Firebase
• group_alias (اختياري): في حال تحديدها، تتم إضافة المختبِرين إلى المجموعة المحدّدة (أو إزالتهم منها).
• service_credentials_file: مسار ملف بيانات اعتماد خدمة Google
• استبدِل firebase_cli_token برمز المصادقة لواجهة سطر الأوامر 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 على مختبِري ضمان الجودة باستخدام التكامل المستمر/التسليم المستمر.