初始化库并验证操作

本页介绍如何在游戏代码中初始化库,并验证其是否将数据上传到 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 文档中详细了解脚本限制