إعداد المكتبة والتحقق من العملية

توضّح هذه الصفحة كيفية إعداد المكتبة في رمز اللعبة والتحقّق من أنّها تحمّل البيانات إلى Google Play. للاطّلاع على مزيد من المعلومات حول وظائف معيّنة في المكتبة، يُرجى مراجعة المستندات المرجعية.

إعداد المكتبة

في طريقة الإعداد في بداية اللعبة، يمكنك إعداد المكتبة من خلال إنشاء مثيل AndroidPerformanceTuner واستدعاء طريقة Start():

using Google.Android.PerformanceTuner;
using UnityEngine;

public class SomeBehaviour : MonoBehaviour
{
    AndroidPerformanceTuner<FidelityParams, Annotation> tuner =
            new AndroidPerformanceTuner<FidelityParams, Annotation>();

    void Start()
    {
        ErrorCode startErrorCode = tuner.Start();
        Debug.Log("Android Performance Tuner started with code: " + startErrorCode);

        tuner.onReceiveUploadLog += request =>
        {
            Debug.Log("Telemetry uploaded with request name: " + request.name);
        };
    }
}

هذا الرمز كافٍ لبدء استخدام أداة Android Performance Tuner وتجهيز لعبتك. تشير بيانات التسجيل إلى وقت بدء Android Performance Tuner ووقت تحميل بيانات القياس عن بُعد إلى واجهات برمجة تطبيقات Google Play Console. لاحقًا، ستجد هذه العبارات في السجل للتحقق من أن المكون الإضافي يعمل بشكل صحيح.

التهيئة المتأخرة (Vulkan فقط)

إذا كانت لعبتك تستهدف Vulkan وتستخدم Android Frame Pacing، يجب أن يكون لأداة Android Performance Tuner تهيئة متأخرة:

IEnumerator Start()
{
    yield return new WaitForEndOfFrame();
    ErrorCode startErrorCode = tuner.Start();
    Debug.Log("Android Performance Tuner started with code: " + startErrorCode);

    tuner.onReceiveUploadLog += request =>
    {
        Debug.Log("Telemetry uploaded with request name: " + request.name);
    };
}

التحقّق من الفاصل الزمني بين عمليات تحميل بيانات القياس عن بُعد

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

للتحقّق من ضبط الفاصل الزمني على 30 ثانية، اتّبِع الخطوات التالية:

  1. اختَر Google > Android Performance Tuner للوصول إلى الإعدادات.
  2. اختَر علامة التبويب إعدادات القياس وانقر على استخدام الإعدادات المتقدّمة.
  3. تأكَّد من أنّ حقل الفواصل الزمنية (بالدقائق) يحتوي على 0.5.
علامة التبويب &quot;إعدادات القياس&quot; في المكوّن الإضافي لأداة Android Performance Tuner في Unity تعرض الفواصل الزمنية التي تم ضبطها على 0.5 دقيقة
علامة التبويب إعدادات القياس في المكوّن الإضافي

التحقّق من التشغيل الصحيح

إذا كنت تستخدم IL2CPP أو ميزة "إزالة الرموز"، يُرجى الاطّلاع على مقالة إدارة ميزة "إزالة الرموز".

أنشئ لعبتك لنظام Android. أثناء تشغيل اللعبة على جهاز، افتح نافذة Terminal على الكمبيوتر وشغِّل adb logcat:

adb logcat

في ناتج adb logcat، ابحث عن "TuningFork" (لأنّ Tuning Fork هو الاسم الداخلي للمكتبة):

02-03 16:55:45.103 10511 10536 I TuningFork: Got settings from tuningfork/tuningfork_settings.bin
02-03 16:55:45.103 10511 10536 I TuningFork: Using local file cache at /data/user/0/com.Unity3d.BoatAttackDay/cache/tuningfork
02-03 16:55:45.105 10511 10536 I TuningFork: OpenGL version 3.2
02-03 16:55:45.105 10511 10536 I TuningFork: TuningFork.GoogleEndpoint: OK
02-03 16:55:45.106 10511 10611 I TuningFork: Creating directory /data/user/0/com.Unity3d.BoatAttackDay/cache/tuningfork
02-03 16:55:45.106 10511 10536 I TuningFork: TuningFork Settings:

[...]

02-03 16:55:45.116 10511 10536 I Unity   : Tuningfork started with code: Ok
02-03 16:55:45.107 10511 10536 I TuningFork: TuningFork initialized
02-03 16:55:45.107 10511 10536 I UnityTuningfork: Swappy backend: 1
02-03 16:55:45.107 10511 10536 I TuningFork: Creating directory /data/user/0/com.Unity3d.BoatAttackDay/cache/tuningfork/V1
02-03 16:55:45.110 10511 10613 I TuningFork: OpenGL version 3.2
02-03 16:55:45.110 10511 10613 I TuningFork:Web: Connecting to: https://performanceparameters.googleapis.com/v1/applications/com.Unity3d.BoatAttackDay/apks/1:generateTuningParameters

إذا ارتكبت خطأ أثناء إعداد المكوّن الإضافي، مثل نسيان ضبط مفتاح واجهة برمجة التطبيقات، سيظهر لك خطأ في سجلّات الإعداد:

02-03 16:49:44.970  8815  8831 I TuningFork: Got settings from tuningfork/tuningfork_settings.bin
02-03 16:49:44.971  8815  8831 I TuningFork: Using local file cache at /data/user/0/com.Unity3d.BoatAttackDay/cache/tuningfork
02-03 16:49:44.972  8815  8831 I TuningFork: OpenGL version 3.2
02-03 16:49:44.972  8815  8831 W TuningFork.GE: The API key in Tuning Fork TFSettings is invalid
02-03 16:49:44.972  8815  8831 E TuningFork: TuningFork.GoogleEndpoint: FAILED
02-03 16:49:44.973  8815  8831 I Unity   : Tuningfork started with code: BadParameter

تأكَّد من أنّ أداة Android Performance Tuner تحمّل بيانات القياس عن بُعد. إذا ظهر لك TuningFork initialized في السجلّات، انتظِر قليلاً وابحث عن السجلّات التي تشير إلى أنّه يتم تحميل بيانات القياس عن بُعد.

02-03 16:58:00.552 10511 10611 I TuningFork:Web: Connecting to: https://performanceparameters.googleapis.com/v1/applications/com.Unity3d.BoatAttackDay/apks/1:uploadTelemetry
02-03 16:58:00.898 10511 10611 I TuningFork:Web: Response code: 200
02-03 16:58:00.898 10511 10611 I TuningFork:Web: Response message: OK
02-03 16:58:00.899 10511 10611 I TuningFork.GE: UPLOAD request returned 200 {}

يمكنك أيضًا البحث في السجلّات عن "جارٍ الاتصال بـ:". تتبع هذه الرسالة رمز الاستجابة بعد بضعة أسطر.

إذا لم تظهر لك سجلّات تحميل بيانات القياس عن بُعد، تأكَّد من ضبط الفاصل الزمني بين كل عملية تحميل في إعدادات Android Performance Tuner على قيمة صغيرة، مثل 30 ثانية.

إدارة عملية تجريد الرموز

يستخدم "Google.Protobuf.dll" الانعكاس. أثناء تجريد الرمز، قد تتم إزالة بعض الرموز المطلوبة. لتجنُّب هذه الإزالة، يحتوي المكوّن الإضافي على ملف link.xml يتضمّن معلومات حول الرموز التي يجب الاحتفاظ بها. إذا كنت بحاجة إلى بعض وظائف protobuf التي تستخدم الانعكاس وتم تفعيل ميزة تجريد الرموز، أضِف هذه المعلومات إلى ملف link.xml للحفاظ على الرموز.

لمزيد من المعلومات حول إزالة الرموز البرمجية المُدارة، يُرجى الاطّلاع على مستندات Unity.

إذا كنت بحاجة إلى الاحتفاظ بجميع الرموز في protobuf، أضِف ملف link.xml إلى مشروعك يحتوي على ما يلي:

<linker>
  <assembly fullname="Google.Protobuf" preserve="all"/>
</linker>

التجميع المُسبَق (AOT)

يجب إجراء عملية التجميع المسبق لبرنامج IL2CPP الخلفي والإصدارَين 2017 و2018 من Unity (ولكن ليس للإصدارات الأحدث من Unity).

قد لا ينشئ برنامج التجميع AOT رمزًا للطرق العامة. عليك فرض برنامج التجميع لإنشاء الرمز البرمجي المناسب المطلوب لـ protobuf من خلال إضافة الطريقة التالية:

using Google.Protobuf.Reflection;
using UnityEngine.Scripting;

...

// Don't call this method.
[Preserve]
void ExampleOfForceReflectionInitializationForProtobuf()
{
    FileDescriptor.ForceReflectionInitialization<Scene>();
    FileDescriptor.ForceReflectionInitialization<ShadowType>();
    FileDescriptor.ForceReflectionInitialization<LevelType>();
    ...
    // Add FileDescriptor.ForceReflectionInitialization<T> for each generated enum.
    // You can find the list of enums in DevTuningfork.cs -> enum section
    // or in the list of enums in Google -> Android Performance Tuner.
}

لمزيد من المعلومات حول القيود المفروضة على النصوص البرمجية، يُرجى الاطّلاع على مستندات Unity.