Unity接入指南-腾讯WeTest

解压压缩包，将PerfSightPlugin下的Plugins以及PerfSightScripts文件夹复制到游戏的Assets目录中。

iOS构建请额外配置如下内容：

在Xcode 目标Target > General > Frameworks, Libraries, and Embedded Content下添加 libz.tdb 依赖库

1. 初始化（必选）

选择第一个或主场景，在任意脚本文件中调用如下代码（建议选择较早加载的脚本）进行初始化。一般在Awake函数中调用。

void Awake()
{
…

PerfSightAgent.EnableDebugMode(); //可选，调试情况下打开日志
PerfSightAgent.InitContext("apm appid");//必选，AppId请联系PerfSight获取
…
}

2. 用户标识（必选）

public static void SetUserId(string openId)

功能：设置OpenId

参数 openId: openId信息

返回值：无

PerfSight既能反映整体大盘的外网性能状况，也提供接口进行单用户的性能回溯，通过PerfSightAgent.SetUserId设置玩家OpenId之后，在Web端可以通过玩家OpenId查看其性能数据，准确还原玩家游戏性能，此接口可在程序任意位置调用，一般从MSDK组件的登录回包中获取。

3. 场景开始标记（必选）

public static void MarkLoadlevel(string sceneName)

功能：标记场景开始

参数 sceneName: 场景标识

返回值：无

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

4. 场景加载结束（可选）

public static void MarkLoadlevelCompleted()

功能：标识场景加载结束

参数：无

返回值：无

在场景加载完毕之后通过调用PerfSightAgent.MarkLoadlevelCompleted()进行场景结束的标记，通过调用此接口可计算场景的加载时间。一般地，MarkLoadlevelCompleted需要在场景加载完毕之后的GameObject脚本中被调用。在同一个逻辑场景中多次调用此接口无效，其只会执行一次。

5. 场景结束标记（必选）

public static void MarkLevelFin()

功能：标识场景加载结束

参数：无

返回值：无

通过PerfSightAgent.MarkLevelFin ()函数来标记场景结束（非必要），如果没有通过调用PerfSightAgentt.MarkLevelFin()函数来结束场景，整个场景的时间以下一次调用PerfSightAgent.MarkLoadlevel ("LevelName ")的时间为场景结束时间，但这可能会对标记区间的FPS计算有影响,为了提高计算的精度最好手动标记结束。默认情况下，PerfSight只会在MarkLoadlevel开始后采集数据，并在MarkLevelFin之后结束采集数据并上传到PerfSight服务器，为了便于查看数据，推荐上传数据的场景时间大于5秒，过短的场景无法采集性能数据。

6. 场景标记（可选）

6.1 正常标签（可选）

public static void BeginTag(string tagName)

功能：开始场景内区域标记

参数tagName：标记标识符

返回值：无

public static void EndTag()

功能：结束区域标记

参数：无

返回值：无

在PerfSight的一个逻辑场景中，由于场景中各个阶段需要渲染的资源或者效果不一致，因此需要突出逻辑场景中的某一段或者多段区域，因此增加了BeginTag标记。通过BeginTag接口来标记一个标签的开始，标签和场景是依附的关系，如果当前没有MarkLoadlevel进行标记，则BeginTag无效，BeginTag中继承MarkLoadlevel中的画质。通过EndTag结束当前的标签，如果没有调用EndTag，则SDK中会默认自动插入一个EndTag的标记。两者的关系图如下。

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

6.2 区域剔除（可选）

public static void BeginExclude()

功能：开始区域剔除，MMO游戏可以用于剔除挂机

参数：无

返回值：无

public static void EndExclude()

功能：结束区域剔除

参数：无

返回值：无

在MMO游戏中，可能需要将挂机行为的数据进行剔除，可使用BeginExclude以及EndExclude进行标记。

7. 网络延时（必选）

PerfSight本身并不提供计算网络延时的接口，只提供网络延时的上报分析，因此具体的网络延时由游戏客户端进行计算，并通过PerfSightAgent. UpdateNetLatency ()接口来上传，其可独立于主线程，可以通过在一个协程中进行调用。

IEnumerator updateNTL()
    {
        while (true)
        {
			//客户端计算网络延时ntl
            PerfSightAgent.UpdateNetLatency(ntl);
            yield return new WaitForSeconds(1f);
        }
 }

PerfSight的后台会对上传的时延数据进行地域，场景以及运营商等多个维度的统计分析。

8. 机型档位判定接口（可选）

public static int CheckDeviceClass(string domainName)

功能：获取机型分档

参数 domainName：配置文件中的一个配置项名称

返回值：设备分档值

public static void CheckDeviceClassAsync(string domainName, TApmDeviceClassCallbackDelegatehandler)

功能：异步获取机型分档

参数 domainName：配置文件中的一个配置项名称

参数 handler：回调handler

返回值：无

云控机型分档分为同步接口CheckDeviceClass和异步回调接口CheckDeviceClassAsync，参数为QCC配置文件中configureList配置域数组中的某个配置域，同步接口中不会发生网络请求，其根据缓存的云端配置文件中的相关定义判断并返回当前的机型档位，异步接口中会发生网络请求，保证获取到最新的配置文件，否则会返回失败，为一个负数的错误码。如果需要使用此接口，则需要将默认的机型档位配置放置于StreamingAssets目录中（iOS的默认配置文件命名规则为：QCC_{appId}IOS 或 tapm_qcc_ios_default,Android的默认配置文件命名规则为：QCC{appId}），首次使用此接口时，其使用本地的配置文件，同时后台线程进行云端拉取配置文件，后续调用此接口时，则返回根据云端配置中定义的机型档位。异步接口保证每次都会去服务端拉取最新的配置文件，成功后调用注册的回调接口，如果在拉取文件过程中或者发生其它错误则返回的机型档位值为负数，需要做业务侧做特别的处理。

此接口用于机型的分档配置，如果业务侧已经有具体的机型分档模型，则此接口无需关注

注意：CheckDeviceClassAsync的回调并不在Unity主线程。
调试

可以通过预发布服进行测试，待测试完成之后可以发布到线上，测试步骤如下：

1、PC通过USB连接目标手机

2、通过PC打开命令行,Windows上为CMD，Mac上为Terminal

3、输入 adb shell

4、cd /data/local/tmp

5、touch QCC_PRE_PUB

6、chmod 777 QCC_PRE_PUB

至此，手机本地的预发布度环境设置完成，运行游戏，通过Adb可以看到QCC PrePub Mode enabled的信息

9. 全局画质设定接口（可选）

public static void SetQuality(int sceneQuality)

功能：设定场景画质

参数 sceneQuality：画质值

返回值：无

SetQuality用于定义画质，此画质为一个多维度的组合编码值，PerfSight后台会根据各个细分画质进行统计分析，此接口可以在任意位置中调用，可以调用一次，全局生效，也可以调用多次，会以最后一次为准。

10.设置机型分档（可选）

public static void SetCustomizedDeviceClass(int deviceLevel)

功能：设置机型分档，后台会按照设定的机型分档做数据聚合

参数 deviceLevel：机型分档值，NOTE：机型分档值需大于等于1

返回值：无

设置机型分档, 可以使用SetCustomizedDeviceClass, 后台会按照设定的机型分档做数据聚合， NOTE：机型分档值需大于等于1

11. 目标帧率设定接口（可选）

public static void SetTargetFramerate(int target)

功能：设定目标帧率

参数 target：目标帧率

返回值：无

为了区分各种高帧率模式，提高PerfSight后台分类统计的精度，提供了SetTargetFrameRate接口用于设定目标帧率，如30,40,50或者60，PerfSight的后台会按照目标帧率再进行相应的分类统计。

12. 自定义设置版本号（可选）

public static void SetVersionIden(string version)

功能：设定目标帧率

参数 version：资源版本号

返回值：无

为了解决热更版本号的问题，可以通过通过SetVersionIden接口进行游戏资源版本号的自主设定。

13. 自定义设置版本号（可选）

public static void PostEvent(int key, string value)

功能：玩家染色事件

参数 key：事件键

参数 value：事件值

返回值：无

此染色事件可用于标记特定玩家或者特定事件，比如可以标记当前对局是或否有作弊、标记当前玩家的属性等等，后台可以配置通过此事件进行过滤筛选等操作。Key值可在PerfSight平台上进行自定义配置。

14.自定义数据上报(可选)

void PostValueF(string catgory, string key, float a);
void PostValueF(string catgory, string key, float a, float b);
void PostValueF(string catgory, string key, float a, float b, float c);
void PostValueI(string catgory, string key, int a);
void PostValueI(string catgory, string key, int a, int b);
void PostValueI(string catgory, string key, int a, int b, int c);
void PostValueS(string catgory, string key, string value);
void BeginTupleWrap(string key);
void EndTupleWrap();

PostValue系列用于上报自定义数据，PerfSight后台将属于同一个Category的数据，分别对Key进行聚合分析，如上报函数耗时PostValueF(“FuntionTime”, “Update”, 0.33f)，"FuntionTime"表示类别，"Update"表示具体的Key值，0.33表示具体的函数耗时值。

BeginTupleWrap和EndTupleWrap用于结构体数据的定义，其为自定义数据提供了强大的扩展能力，提供了复合键值以及多维度数据的分析能力。通过BeginTupleWrap上传的数据，在后台会抽象为一个结构体，结构体名为TupleName， BeginTupleWrap和EndTupleWrap中需要通过PostValue系列函数指定对应的键值和数据值。
自定义数据使用具体事例如下：

// 上传单条自定义数据
PostValueF("FuntionTime", "Update", 0.33f)
//上传一个结构体， 结构体的名字为ModuleCostAnalyse函数耗时分析
BeginTupleWrap("ModuleCostAnalyse")

//通过TUPLE_KEY表明这是一个键值，键名为"Module"，对应的值为"ShaderModel"
PostValueS(TUPLE_KEY, "Module", "ShaderModel");

//通过TUPLE_VALUE表明这是需要统计分析的维度，键名为"Parse"，对应的值为23"
PostValueI(TUPLE_VALUE, "Parse", 23);//表明Parse模块需要23ms

PostValueI(TUPLE_VALUE, "exec", 50);//表明exec模块需要50ms

//结束封装
EndTupleWrap()

其在PerfSight后台会抽象一个二维表的模型，并进行统计分析：

类别	键值	值
FuntionTime	Update	0.33
ModuleCostAnalyse	Module	ShaderModel
ModuleCostAnalyse	Parse	23
ModuleCostAnalyse	exec	50

PerfSight后台可按照项目需求，针对自定义数据按照版本、场景、机型进行聚合分析，如最大值、最小值、总和、平均值、分布等计算。

注意事项：
1.不建议设置过多的类别名与键值名，自定义数据分析界面上仅最多支持60种自定义数据的展示。

2.建议在场景中上报自定义数据，否则上报的数据不会在对局数据中展示。

3.在自定义数据分析查看数据时，需要确认所选版本正确，如果统计数据显示“-”，一般会在配置统计后，十分钟之内展示结果。

4.上报的自定义数据名称不能包含逗点‘.'和中文，在配置界面可以在展示时将对应字段配置成中文。

15. TDM配置

使用PerfSight进行上报时需要配置TDM组件，TDM分为国内版和海外版，Android在AndroidManifest.xml中进行配置iOS在info.plist中进行配置。
在进行测试前请确认已配置TDM上报域名，在配置时若使用TDM测试环境则上报数据不会被PerfSight接受。具体配置方法如下。
国内业务域名 https://hc.tdm.qq.com:8013/tdm/v1/route

海外业务域名 https://sg.tdatamaster.com:8013/tdm/v1/route

Android端配置方法：

将如下代码配置在app目录的 AndroidManifest.xml 中的 Application 节点下，AppId为调用initContext时传入的AppId，域名请根据对应业务设置。

<meta-data android:name="GCloud.TDM.AppId" android:value="AppId" />
<meta-data android:name="GCloud.TDM.TGEMIT_ROUTER_ADDRESS_FORMAL" android:value="业务域名" />
<meta-data android:name="GCloud.TDM.Test" android:value="false" />

iOS端配置方法：

在 Xcode 工程的 info.plist 中增加以下配置，AppId为调用initContext时传入的AppId，域名请根据对应业务设置。

<key>TDM</key>
<dict>
    //必填
    <key>AppId</key>
    <string>XXXX</string>
    <key>TGEMIT_ROUTER_ADDRESS_FORMAL</key>
    <string>业务域名</string>
	<key>Test</key>
    <false/>
</dict>

16. 调试

在PerfSightAgent.InitContext(“123456334”)接口打开调试信息，运行游戏，通过Android的logcat查看接入是否成功，通过adb shell进入shell环境，输入”logcat | grep -i xclient“查看debug信息，如果看到“TAPM init finished”的字样则意味着初始化成功。

进入场景，操作游戏，结束场景，查看debug信息，如果有”file send successfully”的字样代表数据上传成功。

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

Unity接入指南