إضافة دوال تسجيل مدة التحميل

من المهم تسجيل أحداث التحميل في لعبتك لسببَين:

  1. لتجنُّب التأثير سلبًا على بيانات وقت عرض اللقطة أثناء التحميل
  2. لتحليل أوقات التحميل لمعرفة متى وأين تكون أوقات التحميل أطول من المقبول.

يمكن أن يتضمّن حدث التحميل بيانات وصفية مرتبطة به:

public class LoadingTimeMetadata
{
    public enum LoadingState
    {
        Unknown = 0,

        /// <summary>
        ///     The first time the game is run.
        /// </summary>
        FirstRun = 1,

        /// <summary>
        ///     App is not backgrounded.
        /// </summary>
        ColdStart = 2,

        /// <summary>
        ///     App is backgrounded.
        /// </summary>
        WarmStart = 3,

        /// <summary>
        ///     App is backgrounded, least work needed.
        /// </summary>
        HotStart = 4,

        /// <summary>
        ///     Asset loading between levels.
        /// </summary>
        InterLevel = 5
    }

    public LoadingState state;

    public enum LoadingSource
    {
        UnknownSource = 0,

        /// <summary>
        ///     Uncompressing data.
        /// </summary>
        Memory = 1,

        /// <summary>
        ///     Reading assets from APK bundle.
        /// </summary>
        Apk = 2,

        /// <summary>
        ///     Reading assets from device storage.
        /// </summary>
        DeviceStorage = 3,

        /// <summary>
        ///     Reading assets from external storage, e.g. SD card.
        /// </summary>
        ExternalStorage = 4,

        /// <summary>
        ///     Loading assets from the network.
        /// </summary>
        Network = 5,

        /// <summary>
        ///     Shader compilation.
        /// </summary>
        ShaderCompilation = 6,

        /// <summary>
        ///     Time spent between process starting and onCreate.
        /// </summary>
        PreActivity = 7,

        /// <summary>
        ///     Total time spent between process starting and first render frame.
        /// </summary>
        FirstTouchToFirstFrame = 8,

        /// <summary>
        ///     Time from start to end of a group of events.
        /// </summary>
        TotalUserWaitForGroup = 9
    }

    public LoadingSource source;

    /// <summary>
    ///     0 = no compression, 100 = max compression
    /// </summary>
    public int compression_level;

    public enum NetworkConnectivity
    {
        Unknown = 0,
        Wifi = 1,
        CellularNetwork = 2
    }

    public NetworkConnectivity network_connectivity;

    /// <summary>
    ///     Bandwidth in bits per second.
    /// </summary>
    public ulong network_transfer_speed_bps;

    /// <summary>
    ///     Latency in nanoseconds.
    /// </summary>
    public ulong network_latency_ns;
}

يمكن أن تكون قيمة أي حقول غير ذات صلة باحتياجاتك صفرًا.

يمكن أن يتضمّن حدث التحميل أيضًا تعليقًا توضيحيًا مرتبطًا به. يمكنك تحديدها بالطريقة نفسها التي تحدّد بها التعليقات التوضيحية لوقت عرض اللقطة، وذلك باستخدام حقل واحد أو أكثر في رسالة Annotation.

Result<ulong> StartRecordingLoadingTime(LoadingTimeMetadata eventMetadata, TAnnotation annotation);

تبدأ هذه الدالة في تسجيل حدث وقت التحميل المرتبط بالبيانات الوصفية والتعليقات التوضيحية المحدّدة، وتملأ Result<ulong>.value لاستخدامه في الدالة StopRecordingLoadingTime().

ErrorCode StopRecordingLoadingTime(ulong handle);

توقف هذه الدالة تسجيل حدث تم بدؤه سابقًا بواسطة StartRecordingLoadingTime(). يتم تحميل الحدث عند تفريغ الجلسة التالية.

جارٍ تحميل وظائف المجموعة

في لعبتك، يمكنك تسجيل عدة أحداث تحميل لفترة تحميل واحدة يراها المستخدم. وتشمل بعض الأمثلة تحميل الملفات وتحميل المشاهد وإلغاء الضغط وتجميع أدوات التظليل.

من المهم إبلاغ أداة Android Performance Tuner بأنّ أحداث التحميل جزء من هذه المجموعة حتى تتمكّن من تقديم إحصاءات أفضل. يمكنك تجميع أحداث التحميل باستخدام دالتي البدء والإيقاف التاليتين لإجراء ذلك.

Result<ulong> StartLoadingGroup(LoadingTimeMetadata eventMetadata, TAnnotation annotation);

تبدأ هذه الدالة مجموعة تحميل مرتبطة بالبيانات الوصفية والتعليقات التوضيحية المحدّدة، وتملأ Result<ulong>.value لاستخدامه في الدالة StopLoadingGroup(). لا يتم استخدام البيانات الوصفية والتعليقات التوضيحية حاليًا من خلال الخلفية في Play، ويمكن ضبط التعليقات التوضيحية فقط على null. ويتم وضع علامة على جميع أحداث التحميل اللاحقة باستخدام معرّف مجموعة فريد.

ErrorCode StopLoadingGroup(ulong handle);

توقف هذه الدالة مجموعة تحميل تم تشغيلها سابقًا بواسطة StartLoadingGroup(). لن تتضمّن أحداث التحميل اللاحقة معرّف مجموعة إلى أن يتم استدعاء StartLoadingGroup() مرة أخرى.

مخطط انسيابي يعرض StartLoadingGroup وStopLoadingGroup يحصران طلبات تحميل مواد العرض
الشكل 1. مثال على مجموعة التحميل

أمثلة

في ما يلي بعض الأمثلة على كيفية إضافة دوال وقت التحميل إلى لعبتك.

أحداث تحميل الملفات

يوضّح مثال الرمز البرمجي التالي كيفية تسجيل أحداث تحميل الملفات في لعبتك.

public RawImage image;

IEnumerator LoadImageFromStreamingAssets(string imageName)
{
    string imagePath = "file://" + Path.Combine(Application.streamingAssetsPath, imageName);
    using (var r = UnityWebRequestTexture.GetTexture(imagePath))
    {
        LoadingTimeMetadata fileLoadingMetadata = new LoadingTimeMetadata()
        {
            state = LoadingTimeMetadata.LoadingState.InterLevel,
            source = LoadingTimeMetadata.LoadingSource.DeviceStorage,
            // Fields are zero by default but they could be set as follows
            compression_level = 0,
            network_connectivity = 0,
            network_transfer_speed_bps = 0,
            network_latency_ns = 0
        };
        Annotation annotation = new Annotation()
        {
            Scene = Scene.MagicalForest
        };
        // Start recording loading time.
        Result<ulong> result = performanceTuner.StartRecordingLoadingTime(fileLoadingMetadata, annotation);
        yield return r.SendWebRequest();
        // Stop recording loading time.
        performanceTuner.StopRecordingLoadingTime(result.value);
        if (r.isNetworkError || r.isHttpError)
        {
            Debug.Log(r.error);
        }
        else
        {
            Texture2D tex = DownloadHandlerTexture.GetContent(r);
            image.texture = tex;
        }
    }
}

أحداث تحميل المشهد

يوضّح مثال الرمز البرمجي التالي كيفية تسجيل أحداث تحميل المشاهد في لعبتك.

IEnumerator LoadScene(int sceneIndex)
{
    LoadingTimeMetadata metadata = new LoadingTimeMetadata()
        {state = LoadingTimeMetadata.LoadingState.InterLevel};
    Annotation annotation = new Annotation() {Scene = (Scene) (sceneIndex + 1)};
    Result<ulong> result = performanceTuner.StartRecordingLoadingTime(metadata, annotation);
    AsyncOperation asyncSceneLoad = SceneManager.LoadSceneAsync(sceneIndex, LoadSceneMode.Single);
    while (!asyncSceneLoad.isDone)
    {
        yield return null;
    }

    performanceTuner.StopRecordingLoadingTime(result.value);
}

جارٍ تحميل وظائف المجموعة

يوضّح مثال الرمز التالي كيفية إضافة دوال تحميل المجموعات إلى لعبتك.

IEnumerator LoadImages()
{
    LoadingTimeMetadata groupMetadata = new LoadingTimeMetadata()
    {
        state = LoadingTimeMetadata.LoadingState.InterLevel,
        source = LoadingTimeMetadata.LoadingSource.DeviceStorage,
    };
    Result<ulong> result = performanceTuner.StartLoadingGroup(groupMetadata, null);
    yield return StartCoroutine(LoadImageFromStreamingAssets("image1.jpeg"));
    yield return StartCoroutine(LoadImageFromStreamingAssets("image2.jpeg"));
    yield return StartCoroutine(LoadImageFromStreamingAssets("image3.jpeg"));
    yield return StartCoroutine(LoadImageFromStreamingAssets("image4.jpeg"));
    var stopErrorCode = performanceTuner.StopLoadingGroup(0);
}