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

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

في ما يلي الخطوات العامة لإنشاء ملف تجاري جديد يستند إلى قاعدة مرجعية:

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

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

إنشاء ملف تعريف أساسي جديد باستخدام AGP 8.2 أو إصدار أحدث

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

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

إعداد وحدة "الملف الشخصي الأساسي"

لتشغيل نموذج وحدة الملف الشخصي الأساسي، اتبع الخطوات التالية:

1. اختَر ملف > جديد > وحدة جديدة.
2. اختَر نموذج منشئ الملف الشخصي المرجعي في لوحة النماذج واضبطه:

   

   في ما يلي الحقول الواردة في النموذج:

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

تحديد أداة إنشاء الملف الشخصي للمرجع

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

ويساعد هذا الإجراء في الحفاظ على قابلية الاستخدام إذا كنت تقتطع CUJs هذه خارج الملف الشخصي الأساسي ورمز المعيار الذي تم إنشاؤه كي يمكن استخدامهما معًا. ويعني ذلك أنّ التغييرات التي يتم إجراؤها على مجموعات عناوين URL الخاصة بعملاءك المستهدفين يتم استخدامها بشكلٍ متسق.

إنشاء الملف الشخصي الأساسي وتثبيته

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

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

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

إنشاء ملف شخصي جديد باسم AGP 8.1

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

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

1. عليك إعداد وحدة قياس ماكرو في مشروع 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 لملف الأداء الأساسي (libs.plugins.androidx.baselineprofile). يسهّل المكوّن الإضافي توليد ملف الأداء الأساسي والحفاظ عليه في المستقبل.

4. لإنشاء الملف الشخصي الأساسي، شغِّل مهام Gradle :app:generateBaselineProfile أو :app:generateVariantBaselineProfile في الوحدة الطرفية.

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

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

إنشاء ملف شخصي جديد بدون نماذج

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

في ما يلي كيفية إنشاء ملف مرجعي باستخدام المكوّن الإضافي 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
   }

   رائع

   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. المثال التالي هو اختبار يشغّل التطبيق وينتظر حالة السكون.

   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"))
   }

   رائع

   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. أنشئ الملف الشخصي من خلال تشغيل مهام :app:generateBaselineProfile أو :app:generateVariantBaselineProfile Gradle.

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

إنشاء ملف تعريف أساسي جديد باستخدام AGP 7.3-7.4

ومن الممكن إنشاء ملفات شخصية غير مباشرة باستخدام الإصدار 7.3-7.4 من AGP، ولكننا ننصح بشدة بالترقية إلى الإصدار 8.1 من AGP على الأقل لتتمكّن من استخدام المكوّن الإضافي Baseline Profile وأحدث ميزاته.

إذا كنت بحاجة إلى إنشاء ملفات تعريف أساسية باستخدام AGP 7.3 أو 7.4، تكون الخطوات مماثلة لخطوات AGP 8.1، مع استثناءات التالية:

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

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

ينشئ أداة إنشاء الملف الشخصي الأساسي ملفًا نصيًا بتنسيق 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 الخاص بتطبيقك لتفعيل عملية compiling لملف Baseline Profile الخاص بالتطبيق في حال عدم توفّر ملفات Cloud Profiles. هذه هي الطريقة الوحيدة لتحميل ملف تعريف شخصي من مصدر غير معروف محليًا.

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

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

قياس أداء الملف الشخصي الأساسي

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

عند تشغيل هذا الإجراء في Android Studio، يحتوي الناتج عن عملية الإنشاء على تفاصيل عن التحسينات في السرعة التي يوفّرها الملف الشخصي الأساسي:

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)

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

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

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

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

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