إنشاء ملفات شخصية أساسية

إنشاء ملفات شخصية تلقائيًا لكل إصدار من التطبيق باستخدام مكتبة Jetpack Macrobenchmark وBaselineProfileRule ننصحك باستخدام الإصدار com.android.tools.build:gradle:8.0.0 أو إصدار أحدث، والذي يتضمّن تحسينات في عملية الإنشاء عند استخدام "ملفات Baseline Profiles".

في ما يلي الخطوات العامة لإنشاء ملف Baseline Profile جديد:

1. إعداد وحدة Baseline Profile
2. حدِّد اختبار JUnit الذي يساعد في إنشاء "ملفات تعريف المرجع".
3. أضِف رحلات المستخدمين الرئيسية (CUJ) التي تريد تحسينها.
4. إنشاء ملف Baseline Profile

بعد إنشاء ملف تعريف الأداء الأساسي، يمكنك قياسه باستخدام جهاز فعلي لتحديد مدى تحسُّن السرعة.

إنشاء ملف Baseline Profile جديد باستخدام الإصدار 8.2 من "أداة فحص Android" أو إصدار أحدث

أسهل طريقة لإنشاء ملف تعريف أساسي جديد هي استخدام نموذج وحدة Baseline Profile، الذي يتوفّر بدءًا من الإصدار Iguana من "استوديو Android" والإصدار 8.2 من Android Gradle Plugin (AGP).

يؤدي نموذج وحدة "أداة إنشاء ملفات Baseline Profile" في "استوديو Android" إلى إتمام عملية إنشاء وحدة جديدة لإنشاء ملفات Baseline Profile وقياس أدائها تلقائيًا. يؤدي تشغيل النموذج إلى إنشاء معظم إعدادات الإصدار النموذجية ورمز التحقّق وإنشاء "الملف الأساسي". ينشئ النموذج رمزًا برمجيًا لإنشاء ملفات تعريف Baseline Profiles وقياس سرعة تشغيل التطبيق.

إعداد وحدة Baseline Profile

لتشغيل نموذج وحدة Baseline Profile، اتّبِع الخطوات التالية:

1. اختَر ملف > جديد > وحدة جديدة
2. اختَر نموذج أداة إنشاء ملفات Baseline في لوحة النماذج واضبطه على النحو التالي:

   

   الحقول في النموذج هي كما يلي:

   • التطبيق المستهدَف: يحدّد التطبيق الذي يتم إنشاء "ملف تعريف المقياس الأساسي" له. عندما يكون لديك وحدة تطبيق واحدة فقط في مشروعك، لن يكون هناك سوى عنصر واحد في هذه القائمة.
   • اسم الوحدة: الاسم الذي تريده لوحدة Baseline Profile التي يتم إنشاؤها.
   • اسم الحزمة: اسم الحزمة الذي تريده لوحدة Baseline Profile
   • اللغة: ما إذا كنت تريد أن يكون الرمز البرمجي الذي تم إنشاؤه بلغة Kotlin أو Java
   • لغة إعدادات الإصدار: ما إذا كنت تريد استخدام Kotlin Script (KTS) أو Groovy لنصوص إعدادات الإصدار.
   • استخدام جهاز مُدار من Gradle: ما إذا كنت تستخدم أجهزة مُدارة من Gradle لاختبار تطبيقك.
3. انقر على إنهاء وسيتم إنشاء الوحدة الجديدة. إذا كنت تستخدم نظام التحكّم في المصدر، قد يُطلب منك إضافة ملفات الوحدة النمطية التي تم إنشاؤها حديثًا إلى نظام التحكّم في المصدر.

تحديد أداة إنشاء ملف Baseline Profile

يحتوي الوحدة التي تم إنشاؤها حديثًا على اختبارات لإنشاء ملف Baseline Profile وقياس أدائه، واختبار بدء تشغيل التطبيق الأساسي فقط. ننصحك بتعزيز هذه المقاييس لتشمل رحلات المستخدمين الشائعة (CUJ) وسير عمل بدء التشغيل المتقدّم. تأكَّد من أنّ أي اختبارات ذات صلة ببدء تشغيل التطبيق مضمّنة في حظر rule مع ضبط includeInStartupProfile على true. في المقابل، ولتحقيق أفضل أداء، تأكَّد من أنّ أي اختبارات غير ذات صلة ببدء تشغيل التطبيق غير مضمّنة في ملف تعريف بدء التشغيل. تُستخدَم عمليات تحسين بدء تشغيل التطبيق لتحديد جزء خاص من "ملف Baseline Profile" يُعرف باسم ملف بدء التشغيل.

يساعد ذلك في الحفاظ على قابلية الصيانة إذا تم تجريد حالات الاستخدام الشائعة هذه خارج رمز ملف Baseline Profile الذي تم إنشاؤه ورمز قياس الأداء، وذلك حتى يمكن استخدامها لكليهما. وهذا يعني أنّه يتم استخدام التغييرات التي يتم إجراؤها على رحلات المستخدمين الشائعة بشكل متّسق.

إنشاء ملف Baseline Profile وتثبيته

يضيف نموذج وحدة Baseline Profile إعداد تشغيل جديدًا لإنشاء Baseline Profile. في حال استخدام إصدارات المنتج، ينشئ "استوديو Android" إعدادات تشغيل متعدّدة لتتمكّن من إنشاء "ملفات تعريف أساسية" منفصلة لكل إصدار.

عند اكتمال عملية تنفيذ إنشاء ملف Baseline Profile، يتم نسخ ملف Baseline Profile الذي تم إنشاؤه إلى الملف src/variant/generated/baselineProfiles/baseline-prof.txt في الوحدة النمطية التي يتم قياس أدائها. تكون خيارات الإصدار إما نوع إصدار أو صيغة إصدار تتضمّن نوع الإصدار.

تم إنشاء ملف Baseline Profile الذي تم إنشاؤه في الأصل في build/outputs. يتم تحديد المسار الكامل حسب صيغة التطبيق أو نوعه الذي يتم إنشاء الملف الشخصي له، وما إذا كنت تستخدم جهازًا تديره Gradle أو جهازًا متصلاً لإنشاء الملف الشخصي. إذا كنت تستخدم الأسماء التي يستخدمها الرمز وإعدادات الإنشاء التي تم إنشاؤها بواسطة النموذج، سيتم إنشاء "ملف تعريف خط الأساس" في الملف build/outputs/managed_device_android_test_additional_output/nonminifiedrelease/pixel6Api31/BaselineProfileGenerator_generate-baseline-prof.txt. من المحتمل ألا تحتاج إلى التفاعل مع هذا الإصدار من "ملف Baseline Profile" الذي تم إنشاؤه مباشرةً إلا إذا كنت تنسخه يدويًا إلى الوحدات المستهدَفة (وهو أمر لا يُنصح به).

إنشاء ملف Baseline جديد باستخدام الإصدار 8.1 من "مجموعة أدوات تطوير Android"

إذا لم تتمكّن من استخدام نموذج وحدة Baseline Profile، استخدِم نموذج وحدة Macrobenchmark ومكوّن Baseline Profile الإضافي في Gradle لإنشاء Baseline Profile جديد. ننصحك باستخدام هذه الأدوات بدءًا من Android Studio Giraffe وAGP 8.1.

في ما يلي خطوات إنشاء ملف تعريف جديد أساسي باستخدام نموذج وحدة Macrobenchmark ومكوّن Baseline Profile الإضافي في Gradle:

1. إعداد وحدة Macrobenchmark في مشروع Gradle
2. حدِّد فئة جديدة باسم BaselineProfileGenerator:

   class BaselineProfileGenerator {
       @get:Rule
       val baselineProfileRule = BaselineProfileRule()
   
       @Test
       fun startup() = baselineProfileRule.collect(
           packageName = "com.example.app",
           profileBlock = {
               startActivityAndWait()
           }
       )
   }

   يمكن أن يحتوي المُنشئ على تفاعلات مع تطبيقك تتجاوز بدء تشغيل التطبيق. يتيح لك ذلك تحسين أداء وقت التشغيل لتطبيقك، مثل قوائم التمرير وتشغيل الرسوم المتحركة والتنقّل داخل Activity. الاطّلاع على أمثلة أخرى لاختبارات تستخدم @BaselineProfileRule لتحسين رحلات المستخدمين الأساسية

3. أضِف المكوّن الإضافي لنظام Gradle الخاص بـ Baseline Profile (libs.plugins.androidx.baselineprofile)، إذ يسهّل هذا المكوّن الإضافي إنشاء ملفات Baseline Profile والحفاظ عليها في المستقبل.

4. لإنشاء ملف Baseline Profile، شغِّل مهمتَي Gradle :app:generateBaselineProfile أو :app:generateVariantBaselineProfile في وحدة التحكّم الطرفية.

   شغِّل أداة الإنشاء كاختبار مزوّد بأدوات على جهاز فعلي مزوّد بإذن الوصول إلى الجذر أو محاكي أو جهاز مُدار من Gradle. إذا كنت تستخدم جهازًا مُدارًا من Gradle، اضبط aosp كـ systemImageSource، لأنّك تحتاج إلى إذن الوصول إلى الجذر لإنشاء "ملف تعريف خط الأساس".

   في نهاية مهمة إنشاء ملف Baseline Profile، يتم نسخ الملف إلى app/src/variant/generated/baselineProfiles.

إنشاء ملف Baseline Profile جديد بدون نماذج

ننصحك بإنشاء "ملف تعريف أساسي" باستخدام نموذج وحدة "ملف التعريف الأساسي" في Android Studio (الخيار المفضّل) أو نموذج Macrobenchmark، ولكن يمكنك أيضًا استخدام مكوّن Baseline Profile الإضافي في Gradle بمفرده. لمزيد من المعلومات حول المكوّن الإضافي لنظام Gradle الخاص بـ Baseline Profile، اطّلِع على مقالة ضبط عملية إنشاء Baseline Profile.

في ما يلي كيفية إنشاء "ملف تعريف أساسي" باستخدام مكوّن Baseline Profile الإضافي في Gradle مباشرةً:

1. أنشئ وحدة com.android.test جديدة، مثل :baseline-profile.

2. اضبط ملف build.gradle.kts للنطاق :baseline-profile باتّباع الخطوات التالية:

   1. طبِّق المكوّن الإضافي androidx.baselineprofile.
   2. تأكَّد من أنّ targetProjectPath يشير إلى الوحدة :app.
   3. يمكنك اختياريًا إضافة جهاز مُدار من Gradle (GMD). في المثال التالي، تكون القيمة pixel6Api31. في حال عدم تحديد ذلك، يستخدم المكوّن الإضافي جهازًا متصلاً، سواء كان محاكيًا أو فعليًا.
   4. طبِّق الإعدادات التي تريدها، كما هو موضَّح في المثال التالي.

   Kotlin

   plugins {
       id("com.android.test")
       id("androidx.baselineprofile")
   }
   
   android {
       defaultConfig {
           ...
       }
   
       // Point to the app module, the module that you're generating the Baseline Profile for.
       targetProjectPath = ":app"
       // Configure a GMD (optional).
       testOptions.managedDevices.devices {
           pixel6Api31(com.android.build.api.dsl.ManagedVirtualDevice) {
               device = "Pixel 6"
               apiLevel = 31
               systemImageSource = "aosp"
           }
       }
   }
   
   dependencies { ... }
   
   // Baseline Profile Gradle plugin configuration. Everything is optional. This
   // example uses the GMD added earlier and disables connected devices.
   baselineProfile {
       // Specifies the GMDs to run the tests on. The default is none.
       managedDevices += "pixel6Api31"
       // Enables using connected devices to generate profiles. The default is
       // `true`. When using connected devices, they must be rooted or API 33 and
       // higher.
       useConnectedDevices = false
   }

   Groovy

   plugins {
       id 'com.android.test'
       id 'androidx.baselineprofile'
   }
   
   android {
       defaultConfig {
           ...
       }
   
       // Point to the app module, the module that you're generating the Baseline Profile for.
       targetProjectPath ':app'
       // Configure a GMD (optional).
       testOptions.managedDevices.devices {
           pixel6Api31(com.android.build.api.dsl.ManagedVirtualDevice) {
               device 'Pixel 6'
               apiLevel 31
               systemImageSource 'aosp'
           }
       }
   }
   
   dependencies { ... }
   
   // Baseline Profile Gradle plugin configuration. Everything is optional. This
   // example uses the GMD added earlier and disables connected devices.
   baselineProfile {
       // Specifies the GMDs to run the tests on. The default is none.
       managedDevices ['pixel6Api31']
       // Enables using connected devices to generate profiles. The default is
       // `true`. When using connected devices, they must be rooted or API 33 and
       // higher.
       useConnectedDevices false
   }

3. أنشئ اختبار Baseline Profile في :baseline-profileوحدة الاختبار. المثال التالي هو اختبار يبدأ التطبيق وينتظر حتى يصبح غير نشط.

   Kotlin

   class BaselineProfileGenerator {
   
       @get:Rule
       val baselineRule = BaselineProfileRule()
   
       @Test
       fun startupBaselineProfile() {
           baselineRule.collect("com.myapp") {
               startActivityAndWait()
           }
       }
   }

   Java

   public class BaselineProfileGenerator {
   
       @Rule
       Public BaselineProfileRule baselineRule = new BaselineProfileRule();
   
       @Test
       Public void startupBaselineProfile() {
           baselineRule.collect(
               "com.myapp",
               (scope -> {
                   scope.startActivityAndWait();
                   Return Unit.INSTANCE;
               })
           )
       }
   }

4. عدِّل ملف build.gradle.kts في وحدة التطبيق، مثل :app.

   1. طبِّق المكوّن الإضافي androidx.baselineprofile.
   2. أضِف تبعية baselineProfile إلى الوحدة :baseline-profile.

   Kotlin

   plugins {
       id("com.android.application")
       id("androidx.baselineprofile")
   }
   
   android {
       // There are no changes to the `android` block.
       ...
   }
   
   dependencies {
       ...
       // Add a `baselineProfile` dependency on the `:baseline-profile` module.
       baselineProfile(project(":baseline-profile"))
   }

   Groovy

   plugins {
       id 'com.android.application'
       id 'androidx.baselineprofile'
   }
   
   android {
       // No changes to the `android` block.
       ...
   }
   
   dependencies {
       ...
       // Add a `baselineProfile` dependency on the `:baseline-profile` module.
       baselineProfile ':baseline-profile'
   }

5. أنشئ الملف الشخصي عن طريق تنفيذ مهمتَي Gradle :app:generateBaselineProfile أو :app:generateVariantBaselineProfile.

6. في نهاية مهمة إنشاء ملف Baseline Profile، يتم نسخ الملف إلى app/src/variant/generated/baselineProfiles.

إنشاء ملف Baseline Profile جديد باستخدام الإصدار 7.3 أو 7.4 من "استوديو Android"

يمكن إنشاء "ملفات تعريف خط الأساس" باستخدام الإصدارات 7.3 إلى 7.4 من "مكوّن Android الإضافي في Gradle"، ولكننا ننصحك بشدة بالترقية إلى الإصدار 8.1 على الأقل حتى تتمكّن من استخدام مكوّن Gradle الإضافي لـ "ملف تعريف خط الأساس" وأحدث ميزاته.

إذا كنت بحاجة إلى إنشاء "ملفات تعريف أساسية" باستخدام الإصدارات 7.3 إلى 7.4 من "مكوّن Android الإضافي لبرنامج Gradle"، تكون الخطوات هي نفسها الخطوات الخاصة بالإصدار 8.1 من "مكوّن Android الإضافي لبرنامج Gradle"، مع الاستثناءات التالية:

• لا تُضِف مكوّن Baseline Profile الإضافي في Gradle.
• لإنشاء "ملفات Baseline"، نفِّذ مهمة Gradle ./gradlew [emulator name][flavor][build type]AndroidTest. على سبيل المثال، ./gradlew :benchmark:pixel6Api31BenchmarkAndroidTest.
• يجب تطبيق قواعد "ملف تعريف خط الأساس" التي تم إنشاؤها على الرمز البرمجي يدويًا.

تطبيق القواعد التي تم إنشاؤها يدويًا

ينشئ مولّد ملفات Baseline Profile ملف نص بتنسيق قابل للقراءة (HRF) على الجهاز وينسخه إلى جهازك المضيف. لتطبيق الملف الشخصي الذي تم إنشاؤه على الرمز، اتّبِع الخطوات التالية:

1. ابحث عن ملف HRF في مجلد الإنشاء الخاص بالوحدة التي تنشئ فيها الملف الشخصي: [module]/build/outputs/managed_device_android_test_additional_output/[device].

   تتّبع الملفات الشخصية نمط التسمية [class name]-[test method name]-baseline-prof.txt، الذي يظهر على النحو التالي: BaselineProfileGenerator-startup-baseline-prof.txt.

2. انسخ الملف الشخصي الذي تم إنشاؤه إلى src/main/ وأعِد تسمية الملف إلى baseline-prof.txt.

3. أضِف تبعية إلى مكتبة ProfileInstaller في ملف build.gradle.kts الخاص بتطبيقك لتفعيل تجميع ملفات Baseline Profile المحلية في حال عدم توفّر ملفات التعريف على السحابة الإلكترونية. هذه هي الطريقة الوحيدة لتحميل ملف Baseline Profile على الجهاز.

   dependencies {
        implementation("androidx.profileinstaller:profileinstaller:1.4.1")
   }
   

4. أنشِئ الإصدار العلني من تطبيقك أثناء تجميع قواعد HRF المطبَّقة في شكل ثنائي وتضمينها في حِزمة APK أو AAB. بعد ذلك، وزِّع تطبيقك كالمعتاد.

قياس أداء "الملف الشخصي للمرجع"

لتقييم "الملف الأساسي"، أنشئ إعدادًا جديدًا لتنفيذ اختبارات Android Instrumented Test Run من إجراء الحاشية الذي ينفّذ مقاييس الأداء المحدّدة في ملف StartupBenchmarks.kt أو StartupBencharks.java. لمزيد من المعلومات عن اختبارات قياس الأداء، يمكنك الاطّلاع على إنشاء فئة Macrobenchmark وأتمتة القياس باستخدام مكتبة Macrobenchmark.

عند تشغيل هذا الرمز البرمجي في Android Studio، ستتضمّن نتيجة الإنشاء تفاصيل حول التحسينات في السرعة التي يوفّرها ملف Baseline Profile:

StartupBenchmarks_startupCompilationBaselineProfiles
timeToInitialDisplayMs   min 161.8,   median 178.9,   max 194.6
StartupBenchmarks_startupCompilationNone
timeToInitialDisplayMs   min 184.7,   median 196.9,   max 202.9

تسجيل جميع مسارات الرموز المطلوبة

في ما يلي المقياسان الرئيسيان لقياس مدة بدء تشغيل التطبيق:

الوقت المستغرَق للعرض الأولي (TTID)

الوقت المستغرَق لعرض الإطار الأول من واجهة مستخدم التطبيق

الوقت المستغرَق للعرض الكامل (TTFD)

وقت التفاعل الأوّلي بالإضافة إلى الوقت اللازم لعرض المحتوى الذي يتم تحميله بشكل غير متزامن بعد عرض الإطار الأوّلي

يتم تسجيل مقياس TTFD مرة واحدة عند استدعاء الطريقة reportFullyDrawn() في ComponentActivity. في حال عدم استدعاء reportFullyDrawn() مطلقًا، يتم إرسال TTID بدلاً من ذلك. قد تحتاج إلى تأخير وقت استدعاء reportFullyDrawn() إلى ما بعد اكتمال التحميل غير المتزامن. على سبيل المثال، إذا كانت واجهة المستخدم تتضمّن قائمة ديناميكية، مثل RecyclerView أو قائمة lazy، قد تتم تعبئة القائمة بمهمة تعمل في الخلفية وتكتمل بعد رسم القائمة لأول مرة، وبالتالي بعد وضع علامة على واجهة المستخدم على أنّها مرسومة بالكامل. في مثل هذه الحالات، لا يتم تضمين الرمز الذي يتم تنفيذه بعد أن تصل واجهة المستخدم إلى حالة الرسم الكامل في "الملف الأساسي".

لتضمين تعبئة القائمة كجزء من "الملف الأساسي"، احصل على FullyDrawnReporter باستخدام getFullyDrawnReporter() وأضِف أداة إعداد تقارير إليه في رمز تطبيقك. أطلِق أداة إعداد التقارير بعد أن تنتهي مهمة الخلفية من ملء القائمة. لا يستدعي FullyDrawnReporter الطريقة reportFullyDrawn() إلا بعد إيقاف جميع أدوات إعداد التقارير. من خلال إجراء ذلك، يتضمّن Baseline Profile مسارات الرموز المطلوبة لتعبئة القائمة. لا يؤدي ذلك إلى تغيير سلوك التطبيق بالنسبة إلى المستخدم، ولكنّه يتيح تضمين جميع مسارات الرموز البرمجية اللازمة في Baseline Profile.

إذا كان تطبيقك يستخدم Jetpack Compose، استخدِم واجهات برمجة التطبيقات التالية للإشارة إلى حالة الرسم الكامل:

• يشير الرمز ReportDrawn إلى أنّ العنصر القابل للإنشاء جاهز للتفاعل على الفور.
• تأخذ ReportDrawnWhen قيمة منطقية، مثل list.count > 0، لتحديد الوقت الذي يصبح فيه العنصر القابل للإنشاء جاهزًا للتفاعل.
• تأخذ الدالة ReportDrawnAfter طريقة تعليق تشير عند اكتمالها إلى أنّ العنصر القابل للإنشاء جاهز للتفاعل.