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 BeginTag(const char* TagName)

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

• static void EndTag()

Function: End marking a region
Parameter: none
Return value: none

Use the BeginTag interface to mark the start of a tag. Tags are attached to scenes. If BeginTag 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 (EndTag has not been called), the SDK will automatically invoke EndTag 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. BeginTag 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();

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.

PerfSight Reporting Configuration

When using PerfSight for reporting, please configure as follows:
Configure in AndroidManifest.xml for Android and info.plist for iOS. Before testing, please confirm that the reporting domain name has been configured. The specific configuration methods are as follows.

Android Configuration

Configure under the Application node in AndroidManifest.xml in the app directory.

<meta-data android:name="PERFSIGHT.REPORT_URL" android:value="reporting domain name" />

Published in Mainland China, reporting domain name: https://android.perfsight.qq.com/apmApi/android/perf
Otherwise: https://pc.perfsight.wetest.net/apmApi/android/perf

iOS Configuration

Please copy the following configuration to info.plist after selecting the correct configuration for the business environment.

<key>PERFSIGHT</key>
<dict>
    <key>REPORT_URL</key>
    <string>reporting domain name</string>
</dict>

Published in Mainland China, reporting domain name: https://ios.perfsight.qq.com/apmApi/ios/perf
Otherwise: https://pc.perfsight.wetest.net/apmApi/ios/perf

Windows Configuration

Set the reporting domain name by calling the SetPCServerURL function, which needs to be called before InitContext.

UPerfSightHelper::SetPCServerURL(reporting domain name);

Published in Mainland China, reporting domain name: pc.perfsight.qq.com
Otherwise: pc.perfsight.wetest.net

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 "./wesight/perfsight" 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 hawk_data.pb_XX generated in the "./wesight/perfsight" 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.