Unreal Integration Guide

Before integrating the SDK, please read the PerfSight SDK Personal Information Processing Policy. After agreeing to the policy, please follow the instructions below to integrate the SDK.

Import PerfSight UE4 Plugin

Copy the PerfSight directory in the Plugins folder to the Plugins directory under the root directory of the UE4 project (create the folder if it does not exist).
Click [File]->[Refresh Visual Studio Project], and then you can see the PerfSight plugin code and directory structure in the Visual Studio project, as shown in the figure.
Compile the PerfSight plugin source code and project source code together. After the compilation is completed, you can see the PerfSight plugin in [Edit]->[Plugins] in the UE4 editor, as shown in the figure.
Note: PerfSight is not enabled by default. When you check the Enabled option, you may need to restart the Editor.
If you need to call the code in the C++ module, you need to configure and add the corresponding module dependencies, as shown below.

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

Interface Description

1. Initialize PerfSight (Required)

• static void InitContext(const char* AppID)

Function: Initialize PerfSight
AppID: Please contact PerfSight to get AppId
Return value: None

2. User Identification (Required)

• static void SetUserId(const char* usrId)

Function: Set OpenId
usrId: OpenId information
Return value: none

PerfSight shows the results of the game's overall performance and provides interfaces for single-user performance tracing. After setting the player's OpenId through SetUserId, the player's performance data can be displayed on the web page which is searched by the player's OpenId. This interface can be called at any position in the program.

3.Scene Marking Function

3.1 Mark Scene Start (Required)

• static void MarkLevelLoad(const char* sceneName);

Function: Mark the start of a scene
sceneName: Scene identifier
Return value: none

By default, PerfSight will not collect performance data until the scene is marked as started. The scene in PerfSight is a logical representation that is not directly related to the physical scene. Therefore, the MarkLoadlevel interface can be called at any position. Generally, UPerfSightHelper::MarkLoadlevel("SceneName") is called before the Application.LoadLevel function in Unity.

3.2 Mark Scene Loading Completion (Optional)

• static void MarkLevelLoadCompleted();

Function: Mark the completion of scene loading
Parameter: none
Return value: none

After a scene is loaded, UPerfSightHelper::MarkLoadlevelCompleted() will mark the end of the scene loading. By calling this interface, the loading time of the scene can be calculated. In general, MarkLoadlevelCompleted should be called in the GameObject script after the scene is loaded. If UPerfSightHelper::MarkLoadlevelCompleted() is called several times within the scene(MarkLeveLoad to MarkLevelFin), only the first call takes effect.

3.3 Mark Scene End (Required)

• static void MarkLevelFin()

Function: Mark the end of the scene
Parameter: none
Return value: none

UPerfSightHelper::MarkLevelFin() function is used to mark the end of the scene (not necessary), and the performance data of the scene will be sent to the PerfSight server asynchronously. If UPerfSightHelper::MarkLevelFin() is not called at the end of a scene, the next UPerfSightHelper::MarkLoadlevel ("LevelName") calling will automatically invoke MarkLevelFin to finish the last scene. However, this may affect the accuracy of performance data calculations. In order to improve the accuracy of the calculation, it is recommended to mark the end of the scene manually. By default, PerfSight only collects data after MarkLoadlevel starts and finishes data collection after MarkLevelFin is been called.

3.4 Tag (Optional)

• static void BeginExtTag(const char* TagName)

Function: Start marking a region in the scene
tagName: Tag identifier
Return value: none

• static void EndExtTag(const char* TagName)

Function: End marking a region
tagName: Tag identifier
Return value: none

Use the BeginExtTag interface to mark the start of a tag. Tags are attached to scenes. If BeginExtTag is called outside the context of the scene, the tag call is ignored. If SetQuality has been called during the scene, the tag shares the same quality value with the scene. When MarkLevelFin is called, but the tag is not finished (EndExtTag has not been called), the SDK will automatically invoke EndExtTag function before MarkLevelFin by default.
The relationship between the scene and tags is shown in the figure below.

Note: Tags are only used to mark certain regions of ​​the logical scene. BeginExtTag cannot be regarded as a simple replacement for MarkLoadlevel. The statistical analysis behavior of tag will also be adjusted according to actual needs.

3.5 Region Exclusion (Optional)

• static void BeginExclude/EndExclude()

Function: region exclusion, can be used for excluding AFK(Away From Keyboard)behavior in MMO games
Parameter: none
Return value: none

For example, it may be necessary to exclude performance data from AFK(Away From Keyboard) behavior or device in power save mode, which may affect the whole performance of the scene.

The relationship between the scene and excluded regions is shown in the figure below.

4. Frame Rate Reporting (Required)

• static void PostFrame(float deltatime)

Function: Report frame rate by calling it in the TICK function.
deltatime: the parameter passed in by the TICK function.
Return value: None.

The PostFrame interface needs to be called every frame. If this function is not called, the PerfSight thread will be blocked and data will not be collected or reported.

5. Network Latency Reporting (Optional)

• static void PostNetworkLatency(int latency)

Function: Report network latency
latency: network latency
Return value: none

PerfSight does not have the ability to detect network latency(RTT time) currently, we only provide the ability to analyze network latency. Therefore, the actual network latency should be detected by the game itself and passed the value to PerfSight SDK by UPerfSightHelper::PostNetworkLatency() interface.

6. Custom Quality Information (Optional)

This interface is used to set custom quality information for PerfSight's custom statistics and queries. This interface can be called at any point. If this method is called more than once, only the last time works. If using this interface, please contact PerfSight helper to configure customized quality setting rules in the web console.

• static void SetQuality(int quality)

Function: Set scene quality
quality: Quality value
Return value: None

Developers can uniformly encode style dimensions, graphics dimensions, or other dimensions that affect performance into an integer number and pass it to PerfSight based on the SetQuality function. The PerfSight server will perform multi-dimensional drill-down and roll-up aggregation calculations based on the received Quality value.

Let's take a real project as an example, and the settings for its quality are shown in the following figure.

There are three dimensions: Graphics, Frame rate, and Style.
There are six options in the Graphics dimension: Smooth, Balanced, HD, HDR, Ultra HD, and Extreme HDR; three options in the Frame rate dimension: Power Saving, Medium, and High; and five options in the Style dimension: Classic, Colorful, Realistic, Soft, Movie. These combinations of options of different dimensions affect the performance of the game, so we need to track the performance of each combination of options in a granular way.
We use an integer number for encoding, with the digits representing the Graphics dimension, the tens representing the Frame rate dimension, and the hundreds representing the Style dimension, resulting in a three-digit integer number.
In the Graphics dimension, we use the numbers 1 to 6 for Smooth to Extreme HDR.
In the Frame rate dimension, we use the numbers 1 to 3 for Power Saving to High.
In the Style dimension, we use the numbers 1 to 5 for Classic to Movie.
In the above figure, for example, HD is selected for Graphics dimension, High is selected for Frame rate dimension, and Classic is selected for Style, then the final encoding value is calculated as follows:

Quality value = 3(HD,digits representing the Graphics) + 3(High)*10(tens representing the Frame rate) + 1(Classic)*100(hundreds representing the Style) = 133
SetQuality(133);

7. Custom Version Number Setting

（Android/iOS Optional）

• static void SetVersionIden(const char* versionName);

Function: Set custom version number
versionName: Resource version number
Return value: None

On the Android or iOS platforms, PerfSight SDK will collect the version number of the app automatically. SetVersionIden can be used to set the game resource version number(logic version number) for hot-update purposes.

（Windows Required）

• public static void SetPCAppVersion(const char* version)

Function: Set custom version number
version: Windows version number
Return value: None

On Windows platforms, SDK does not automatically collect the game version number and needs to be set through this interface.

8. Customized Reporting Interface

8.1 Dyeing Event Reporting (Optional)

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

Function: Player dyeing event
key: Event key
value: Event value
Return value: None

The dyeing event is like the global variable in programming languages. It can be used to mark special events or activities of the player, such as "RooomId" in moba game, whether or not the player has cheating plugins enabled, etc. The dyeing event will be packed and uploaded with every scene. Developers can configure, filter, and view dyeing events on PerfSight web console.

8.2 Custom Data Reporting (Optional)

• 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();
• static void SetPostValueStrMaxLen(int length);

The PostValue series function is used to report custom key-value data. Unlike the Dyeing Event, the key-value series function supports customized aggregation analysis.
BeginTupleWrap and EndTupleWrap are used to define grouped data starting with BeginTupleWrap and ending with EndTupleWrap. A grouped data will be shown in structured ways and can be aggregated as a whole. The specific use of custom data is as follows:

// Upload a single custom data
PostValueF("FuntionTime", "Update", 0.33f)

//Upload a group data, the name of the group is "ModuleCostAnalysis" which indicates the execution time of functions
BeginTupleWrap("ModuleCostAnalyse")

PostValueS("ModuleCostAnalyse", "ModuleName", "ShaderModel");
PostValueI("ModuleCostAnalyse", "Parse", 23);// Indicates that the Parse phrase takes 23ms
PostValueI("ModuleCostAnalyse", "exec", 50);// Indicates that the exec phrase takes 50ms

// End the encapsulation
EndTupleWrap()

On PerfSight Web Console, this group data will be configured as a two-dimensional table model and will be aggregated as follows:

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

PerfSight backend can aggregate and analyze custom data based on version, scene, and device model according to project needs, such as maximum value, minimum value, sum, average, and distribution.

Note: The default string length limit of the value parameter in PostValueS is 256, which can be adjusted through the SetPostValueStrMaxLen interface.

9 Network Route Detection(Optional)

void TraceRoute(const char* ipAddress)

This interface obtains the route of the corresponding ip address. By default, ICMP is used for route probing, because the devices below Android 10 do not have the permission of icmp to send packets, the devices below Android 10 use udp protocol for route probing, in order to prevent the packets from being filtered by the corresponding server, it is necessary to deploy agent service in the server to listen to udp packets.

Routing information:
1, destination URL; 2, route forwarding path; 3, route IP address of each hop; 4, network delay of each hop.

10 Step Event(Windows,Optional)

static void PostStepEvent(const char *category, int stepId, int status, int code, const char *msg, const char *extDefinedKey, bool authorize, bool finish);

Function: Step Event Report
category: The category of step event. Please set to a same value for all event.
stepId: The id of step.
status: The status of step.
code: The error code for current step.
msg: The error msg for current step.
extDefinedKey、authorize: Not used param;
finish: If current step is the final step of work flow.
Return value: None

call while login:
PostStepEvent("category", 0, 0, 0, "","", false, false);

call if login successfully:
PostStepEvent("category", 1, 0, 0, "","", false, false);

call if login failed:
PostStepEvent("category", 2, 404, 0, "","", false, false);

PerfSight Reporting Configuration

void SetUploadServerURL(const char* url)

Function：Setting the reporting domain name. Called before initialization SDK
url：Reporting domain name, please distinguish the reporting domain name according to the platform.
Return value: None

Android Config

China Project Reporting Domain：https://android.perfsight.qq.com
Overseas Project Reporting Domain：https://android.perfsight.wetest.net

iOS Config

China Project Reporting Domain：https://ios.perfsight.qq.com
Overseas Project Reporting Domain：https://ios.perfsight.wetest.net

Windows&Console Config

China Project Reporting Domain：https://pc.perfsight.qq.com
Overseas Project Reporting Domain：https://pc.perfsight.wetest.net

XBOX Config

Xbox platform also need to set the SDK working path, usually fill in the D disk.

void SetWorkSpace(const char* work_space)

Function：Setting the SDK working path. Called before initialization SDK
url：Working path, usually fill in the D disk.
Return value: None

Debugging

Use the EnableDebugMode interface to enable debugging logs and check whether the SDK integration is successful.

Android

Execute the shell environment through adb shell, and enter "logcat | grep -i perfsight" to filter out the PerfSight debug information. If you can see the phrase "PerfSight init finished", the initialization of PerfSight is successful.
Enter the scene, operate the game, end the scene, and check the debug information. The words "file send successfully" means that the data is uploaded successfully.

iOS

You can view the iOS log information by searching for the keyword "perfsight" in NSlog.

Windows

The Windows log is stored in the directory "./quality/performance" and named perf.xxxx.xxx.log. Before you open the log file, you need to close the game; the initialization success keyword: PerfSight init result: 0, and there will be a perf_data.pb_XX generated in the "./quality/performance" folder after the scene ends, indicating that the data is uploaded successfully.

Confirm whether the data is uploaded successfully on the PerfSight page. For projects published in mainland China, please visit https://tapm.wetest.qq.com, otherwise please visit https://tapm.wetest.net.
Visit the "Single User Data"->"Player ID Query" section and use the ID set by the SetOpenId interface to query. If OpenID is not set, use "NA" to query. If you can successfully query the data, the upload is successful. The statistical data will be refreshed about 1 hour after the first upload. Please use the "Player ID Query" to verify the data before the refresh.