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

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

تتكامل أداة App Distribution مع خدمة مشاركة التطبيقات مع الفريق الداخلي في Google Play لمعالجة ملفات AAB التي تحمّلها وتقديم حِزم APK محسّنة للتوافق مع إعدادات أجهزة المختبرِين لديك. يتيح لك توزيع ملفات بتنسيق AAB إجراء ما يلي:

• تشغيل حِزم APK المحسّنة (التي يوفّرها Google Play) والمتوافقة مع أجهزة المختبِرين

• اكتشاف المشاكل المتعلّقة بأجهزة معيّنة وتصحيحها

• اختبِر ميزات حِزم التطبيقات، مثل عرض الميزات في Play وعرض المواد في Play.

• تقليل حجم عمليات التنزيل للمختبِرين

الأذونات المطلوبة

لتحميل حِزم AAB إلى "App Distribution"، عليك ربط تطبيق Firebase بتطبيق في "Google Play". يجب أن يكون لديك مستوى الوصول المطلوب لتنفيذ هذه الإجراءات.

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

ينطبق الجدول التالي على ربط تطبيق Firebase بتطبيق في Google Play، بالإضافة إلى تحميل حِزمات تطبيق Android‏ (AAB).

قبل البدء

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

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

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

3. لإنشاء رابط Firebase يؤدي إلى Google Play وتحميل حِزمات تطبيق Android، تأكَّد من أنّ تطبيقك يستوفي المتطلبات التالية:

   • تم تسجيل كل من التطبيق في Google Play وتطبيق Firebase المتوافق مع Android باستخدام اسم الحزمة نفسه.

   • التطبيق في Google Play مُعدّ على لوحة بيانات التطبيق وموزّع على أحد مسارات Google Play (الاختبار الداخلي أو الاختبار المغلق أو الاختبار المفتوح أو قناة الإصدار العلني).

   • اكتملت مراجعة التطبيق في Google Play وتم نشره. يتم نشر تطبيقك إذا كان عمود حالة التطبيق يعرض إحدى الحالات التالية: "اختبار داخلي" (وليس "اختبار داخلي لمسوّدة") أو "اختبار مغلق" أو "اختبار مفتوح" أو "إصدار".

4. ربط تطبيق Android على Firebase بحساب المطوِّر على Google Play:

   1. في وحدة تحكّم Firebase، انتقِل إلى settings إعدادات المشروع، ثم اختَر علامة التبويب عمليات الدمج.

   2. في بطاقة Google Play، انقر على ربط.
      إذا كان لديك روابط تؤدي إلى Google Play، انقر على إدارة بدلاً من ذلك.

   3. اتّبِع التعليمات الظاهرة على الشاشة لتفعيل عملية دمج App Distribution واختَر تطبيقات Android على Firebase التي تريد ربطها بـ Google Play.

   مزيد من المعلومات حول الربط بـ Google Play

الخطوة 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(task: "bundle", ...)
        # 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!",
            android_artifact_type: "AAB"
        )
    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.