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

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

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(). مرة أخرى.

الشكل 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);
}