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

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

علامة التبويب إعدادات الأدوات في المكون الإضافي

التحقق من العملية الصحيحة

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

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

adb logcat

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

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 {}

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

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

إدارة إزالة الرموز

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

يمكنك قراءة المزيد عن إزالة الرموز المُدارة في مستندات Unity.

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

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

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

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

قد لا ينشئ المحول البرمجي لـ AOT رمزًا للطرق العامة. وتحتاج إلى فرض المحوِّل البرمجي لإنشاء التعليمات البرمجية المناسبة المطلوبة للنموذج الأوّلي عن طريق إضافة الطريقة التالية:

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.