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

يوضّح هذا الدليل كيفية توزيع إصدارات 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.

قبل البدء

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

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

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

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

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

   • تم إعداد التطبيق على لوحة بيانات التطبيق على 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	رمز مميّز لإعادة التحميل يتم عرضه عند مصادقة بيئة التكامل المستمر باستخدام واجهة سطر الأوامر Firebase (يمكنك الاطّلاع على استخدام واجهة سطر الأوامر مع أنظمة التكامل المستمر للحصول على مزيد من المعلومات).
   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(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: رمز المصادقة لواجهة سطر الأوامر 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 على مختبِري ضمان الجودة باستخدام التكامل المستمر/التسليم المستمر.