初始化程式庫並驗證作業

本資訊頁面介紹如何在遊戲程式碼中初始化程式庫,並確認程式庫是否將資料上傳至 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 管理中心的 API。您稍後可以在記錄中找到這些陳述式,以確認外掛程式是否正常運作。

延遲初始化 (僅限 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 分鐘一次),以免遊戲對 API 發出太多要求,這對於資料用量受限的行動數據方案使用者來說尤其重要。此外,較長的間隔也會避免過度使用裝置電池。

如要確認間隔已設為 30 秒,請按照下列指示操作:

  1. 依序選取「Google」>「Android Performance Tuner」即可存取設定。
  2. 選取「Instrumentation Settings」分頁標籤,然後點選「Use advanced settings」
  3. 確認「Intervals (minutes)」欄位中的值為 0.5

外掛程式中的「Instrumentation settings」分頁

驗證是否正確作業

如果您使用的是 IL2CPP 或程式碼清除功能,請參閱「管理程式碼清除功能」。

打造適用於 Android 的遊戲。在裝置上啟動遊戲時,請在電腦上開啟終端機並啟動 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

如果您在設定外掛程式時操作錯誤 (例如忘記設定 API 金鑰),初始化記錄檔中會顯示錯誤訊息:

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 檔案,內含要保留哪些符號的資訊。如果您需要使用反射的 protobuf 功能,且已啟用程式碼清除設定,請將這項資訊新增至 link.xml 檔案以保留符號。

詳情請參閱 Unity 說明文件中的代管程式碼清除功能

如果您需要保留 Protobuf 中的所有符號,請在專案中新增包含以下項目的 link.xml 檔案:

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

預先編譯 (AOT)

IL2CPP 後端和 Unity 2017 和 2018 版都需要預先編譯,但較新版本的 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 說明文件中的指令碼限制