Unreal 接入指南

接入SDK前，请您仔细阅读PerfSight SDK个人信息处理规则，在同意个人信息处理规则后，请按下述指引接入SDK。

导入PerfSight UE4 Plugin

将Plugins文件夹的PerfSight目录拷贝到UE4项目根目录下的Plugins目录（若没有则创建该文件夹）。
点击[文件]->[刷新Visual Studio项目]，然后在 Visual Studio 项目工程中则可以看到 PerfSight plugin 代码以及目录结构，如图所示。 qcc1
将 PerfSight 插件源码和项目源码一起编译，编译完成后则可以在 UE4 编辑器中的[编辑]->[插件]中看到 PerfSight 插件，如图所示。 qcc1
注意:PerfSight 默认是不启用的，当勾选 Enabled 选项时可能需要重新启动 Editor。
如果需要在 C++模块中调用代码，需要配置添加相应的模块依赖，如下所示。

PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore","PerfSight" });

接口说明

1.初始化PerfSight（必选）

static void InitContext(const char* AppID)

功能：初始化PerfSight
参数 AppID: 联系PerfSight获取
返回值：无

2. 用户标识（必选）

static void SetUserId(const char* usrId)

功能：设置usrId
参数 usrId: usrId信息
返回值：无

PerfSight既能反映整体大盘的外网性能状况，也提供接口进行单用户的性能回溯，通过UPerfSightHelper::SetUserId设置玩家OpenId之后，在Web端可以通过玩家OpenId查看其性能数据，准确还原玩家游戏性能，此接口可在程序任意位置调用。

3.场景标记函数

3.1 场景开始标记（必选）

static void MarkLevelLoad(const char* sceneName);

功能：标记场景开始
参数 sceneName: 场景标识
返回值：无

PerfSight提供按需采集的功能。默认情况下， PerfSight将不会进行数据采集，只有当场景开始标记之后才开始采集数据。PerfSight中的场景是逻辑意义上的表示，和实际的物理场景没有直接关系，因此场景标记的接口可在任意位置调用.

3.2 场景加载结束（可选）

static void MarkLevelLoadCompleted();

功能：标识场景加载结束
参数：无
返回值：无

在场景加载完毕之后通过调用UPerfSightHelper::MarkLoadlevelCompleted()进行场景加载结束的标记，通过调用此接口可计算场景的加载时间。在同一个逻辑场景中(MarkLeveLoad到MarkLevelFin)多次调用此接口无效，其只会执行一次。

3.3 场景结束标记（必选）

static void MarkLevelFin()

功能：标识场景加载结束
参数：无
返回值：无

通过UPerfSightHelper::MarkLevelFin ()函数来标记场景结束（非必要），场景的性能数据将异步发送至PerfSight的服务器，如果没有通过调用MarkLevelFin()函数来结束场景，整个场景的时间以下一次调用MarkLoadlevel ("LevelName ")的时间为场景结束时间，但这可能会对标记区间的FPS计算有影响，为了提高计算的精度最好手动标记结束。默认情况下，PerfSight 只在 MarkLoadlevel 启动后收集数据，并在调用 MarkLevelFin 后完成数据收集。

3.4 标签（可选）

有时我们需要关注场景中一些特殊区域的表现，如团战或与 BOSS 的 PVE 战斗，或者需要排除它们的表现数据，以免影响整体表现数据。

static void BeginTag(const char* TagName)

功能：开始场景内区域标记
参数tagName：标记标识符
返回值：无

static void EndTag()

功能：结束区域标记
参数：无
返回值：无

通过BeginTag接口来标记一个标签的开始，标签和场景是依附的关系，如果当前没有MarkLoadlevel进行标记，则BeginTag无效。如果在场景中调用了 SetQuality，BeginTag中继承MarkLoadlevel中的画质值。通过EndTag结束当前的标签，当 MarkLevelFin 被调用，但标签尚未完成（EndTag 尚未被调用）时，SDK 默认会在 MarkLevelFin 之前自动调用 EndTag 函数。
场景和标签之间的关系如下图所示。

注：标签只是用于对逻辑场景的某段区域进行重点标记，不能视BeginTag对MarkLevelLoad简单的替代，Tag的统计分析行为也会根据实际需要做调整。

3.5 区域剔除(可选)

static void BeginExclude()

功能：开始区域剔除，MMO游戏可以用于剔除挂机
参数：无
返回值：无

static void EndExclude()

功能：结束区域剔除
参数：无
返回值：无

例如，可能需要排除挂机行为或设备在省电模式下的性能数据，这可能会影响整个场景的性能。
场景和剔除区域之间的关系如下图所示。

4. 帧率上报（必选）

static void PostFrame(float deltatime)

功能：通过在TICK中调用进行帧率的上报。
参数：deltatime TICK 函数传入的参数。
返回值：无。
如果沒有调用该函数。如果不调用该函数，PerfSight 线程将被阻塞，数据将无法收集或报告。

5. 网络延迟上报（可选）

static void PostNetworkLatency(int latency)

功能：上报游戏逻辑网络延时
参数 mills：网络延时值，单位毫秒
返回值：无

PerfSight目前不具备检测网络延迟（RTT 时间）的功能，只提供网络延时的上报分析的功能。因此具体的网络延时由游戏客户端进行计算，并通过UPerfSightHelper::PostNetworkLatencyy()接口来上传。

6. 自定义画质信息（可选）

此类接口用于设置自定义画质分档，用于PerfSight的自定义统计、查询。此接口可以在任意位置中调用，可以调用一次，全局生效，也可以调用多次，会以最后一次为准。若使用此接口请提前联系PerfSight提供对应规则。

static void SetQuality(int quality)

功能：设定场景画质
参数 quality：画质值
返回值：无

开发人员可以将画质、图形维度或其他影响性能的维度统一编码为整数，并根据 SetQuality 函数将其传递给 PerfSight。PerfSight 服务器将根据接收到的画质值在多个维度聚合计算。
qualitysetting 图中有Graphics, Frame Rate和Style三种维度。
Graphics维度有六个选项： Smooth、Balanced、HD、HDR、Ultra HD 和 Extreme HDR；Frame Rate维度中有三个选项：Power Saving、Medium和High；Style维度中有五个选项：Classic、Colorful、Realistic、Soft、Movie。这些不同维度的选项组合会影响游戏的性能，因此我们需要统计每个维度组合下的性能情况。
我们使用整数进行编码，个位代表Graphics维度，十位代表Frame Rate维度，百位代表Style维度，最终得到一个三位数的整数。
在Graphics维度中，我们使用数字 1 至 6 表示"Smooth"至"Extreme HDR"。
在Frame Rate维度中，我们使用 1 至 3 表示"Power Saving"至"High"。
在Style维度中，我们使用 1 至 5 表示 "Classic"至 "Movie"。
例如，在上图中，Graphics维度选择了HD，Frame Rate维度选择了High，Style维度选择了Classic，那么最终的编码值计算如下：

Quality value = 3(HD,个位代表Graphics) + 3(High)*10(十位代表Frame rate) + 1(Classic)*100(百位代表Style) = 133
SetQuality(133);

7. 版本号设定（可选）

（Android/iOS 可选）

static void SetVersionIden(const char* versionName);

功能：设置游戏资源版本号
参数 versionName：游戏资源版本号
返回值：无

在 Android 或 iOS 平台上，PerfSight SDK 会自动收集应用程序的版本号。可以通过通过SetVersionIden接口进行游戏资源版本号的自主设定。

（Windows 必选）

public static void SetPCAppVersion(const char* version)

功能：设定自定义版本号
参数 version：PC版本号
返回值：无

在 Windows 平台上，SDK不自动采集游戏版本号，需要通过接口设置。

8. 自定义上报接口系列接口

8.1 玩家染色（可选）

static void PostEvent(int key, const char* info = "nA")

功能：玩家染色事件
参数 key：事件键
参数 info：事件值
返回值：无

染色事件就像编程语言中的全局变量。它可用于标记玩家的特殊事件或活动，如 moba 游戏中的 "RoomId"、玩家是否启用了作弊插件等。染色事件将随每个场景上传。开发人员可以在 PerfSight 控制台上配置、过滤和查看染色事件。

8.2 自定义数据上报（可选）

static void PostValueF(const char* catgory, const char* key, float a);
static void PostValueF(const char* catgory, const char* key, float a, float b);
static void PostValueF(const char* catgory, const char* key, float a, float b, float c);
static void PostValueI(const char* catgory, const char* key, int a);
static void PostValueI(const char* catgory, const char* key, int a, int b);
static void PostValueI(const char* catgory, const char* key, int a, int b, int c);
static void PostValueS(const char* catgory, const char* key, const char* value);
static void BeginTupleWrap(const char* TupleName);
static void EndTupleWrap();

PostValue 系列函数用于报告自定义键值数据。与染色事件不同，键值系列函数支持自定义的聚合分析。
BeginTupleWrap 和 EndTupleWrap 用于定义从 BeginTupleWrap 开始到 EndTupleWrap 结束的分组数据。分组数据将以结构化方式显示，并可作为一个整体进行汇总。自定义数据的具体用法如下：

// 上传单条自定义数据
PostValueF("FuntionTime", "Update", 0.33f)

//上传一组名为 "ModuleCostAnalysis"的数据，表示函数的执行时间
BeginTupleWrap("ModuleCostAnalyse")

PostValueS("ModuleCostAnalyse", "ModuleName", "ShaderModel");
PostValueI("ModuleCostAnalyse", "Parse", 23);//表示 Parse 耗时 23ms 
PostValueI("ModuleCostAnalyse", "exec", 50);// 表示 exec 耗时 50ms

// 结束ModuleCostAnalyse数据
EndTupleWrap()

在 PerfSight 控制台上，该组数据将被配置为二维表格模型，并按如下方式展示：

Category	Key	Value
FuntionTime	Update	0.33
ModuleCostAnalyse	Module	ShaderModel
ModuleCostAnalyse	Parse	23
ModuleCostAnalyse	exec	50

PerfSight 后端可根据项目需要，基于版本、场景和设备模型聚合和分析自定义数据的最大值、最小值、总和、平均值和分布。

PerfSight上报配置

使用PerfSight进行上报时，请按如下指引配置
Android在AndroidManifest.xml中进行配置，iOS在info.plist中进行配置。在进行测试前请确认已配置上报域名。具体配置方法如下。

Android配置

在app目录的 AndroidManifest.xml 中的 Application 节点下进行配置。

<meta-data android:name="PERFSIGHT.REPORT_URL" android:value="上报域名" />

国内环境上报域名：https://android.perfsight.qq.com/apmApi/android/perf
海外环境上报域名：https://android.perfsight.wetest.net/apmApi/android/perf

iOS配置

请根据业务环境选择正确配置后，将如下配置复制到info.plist。
国内环境：

<key>PERFSIGHT</key>
<dict>
    <key>REPORT_URL</key>
    <string>上报域名</string>
</dict>

国内环境上报域名：https://ios.perfsight.qq.com/apmApi/ios/perf
海外环境上报域名：https://ios.perfsight.wetest.net/apmApi/ios/perf

Windows配置

通过调用SetPCServerURL函数设置，该函数需要在InitContext前调用。

PerfSightAgent.SetPCServerURL(上报域名);

国内环境上报域名：pc.perfsight.qq.com
海外环境上报域名：pc.perfsight.wetest.net

调试

通过EnableDebugMode接口打开调试信息，确认PerfSight接入是否成功。

Android

通过Android的logcat查看接入是否成功，通过adb shell进入shell环境，输入”logcat | grep -i perfsight“查看debug信息，如果看到“PerfSight init finished”的字样则意味着初始化成功。进入场景，操作游戏，结束场景，查看debug信息，如果有”file send successfully”的字样代表数据上传成功。

iOS

iOS平台可通过NSlog查看关键字为“perfsight”的关键字获取log信息。

PC

PC平台日志在./wesight/perfsight下查看如perf.xxxx.xxx.log，查看时需要关闭游戏;初始化成功关键字：PerfSight init result: 0，场景结束后日志文件夹下有hawk_data.pb_XX生成，代表数据上传成功。

在PerfSight页面中确认数据是否上报成功，国内业务请访问 https://tapm.wetest.qq.com ，国外业务请访问 https://tapm.wetest.net 。访问分栏 “单用户数据”->“玩家ID查询”，通过使用SetOpenId接口设置的id进行查询，若未设置通过“NA”进行查询，可以成功查询数据即为上报成功了。大盘数据在首次上报1小时左右刷新，刷新前请使用“玩家ID查询”查验数据。

Unreal 接入指南

导入PerfSight UE4 Plugin​

接口说明

1.初始化PerfSight（必选）​

2. 用户标识（必选）​

3.场景标记函数​

3.1 场景开始标记（必选）​

3.2 场景加载结束（可选）​

3.3 场景结束标记（必选）​

3.4 标签（可选）​

3.5 区域剔除(可选)​

4. 帧率上报（必选）​

5. 网络延迟上报（可选）​

6. 自定义画质信息（可选）​

7. 版本号设定（可选）​

（Android/iOS 可选）​

（Windows 必选） ​

8. 自定义上报接口系列接口​

8.1 玩家染色（可选）​

8.2 自定义数据上报（可选）​