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

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

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

• يمكنك تشغيل حِزم APK محسّنة (يعرضها Google Play) ومُحسَّنة لتعمل على أجهزة المختبِرين.

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

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

• يمكنك تقليل حجم الملفات التي يتم تنزيلها من قِبل المختبِرين.

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

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

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

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

قبل البدء

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

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

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

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

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

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

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

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

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

   3. اتّبِع التعليمات الظاهرة على الشاشة لتفعيل عملية دمج App Distribution واختيار تطبيقات Firebase المتوافقة مع Android المطلوب ربطها بـ 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 الذي تريد تحميله إذا لم يتم تحديد المسار، يحدد الخط السريع موقع الملف من الممر الذي تم إنشاء الملف فيه.
   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(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 يومًا على انتهاء صلاحية الإصدار، يظهر إشعار بانتهاء الصلاحية فيconsole وفي قائمة الإصدارات لدى المختبِر على جهاز الاختبار.

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

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

المَعلمات

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

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

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

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

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