初始化库并验证操作

本页介绍如何在游戏代码中初始化库,并验证其是否将数据上传到 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。
Android Performance Tuner Unity 插件中的“Instrumentation Settings”标签页,其中显示“Intervals”设置为 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 文档。