Unity Integration Guide

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

Unzip the compressed package and copy the Plugins and Scripts folders under PerfSightPlugin to the Assets directory of the game.

1. Initialization (Required)

Call the following functions in the script of the first or main scene to initialize PerfSight: (Prefer to call the initial functions in the Awake function)

void Awake()
{
    // ...
    PerfSightAgent.EnableDebugMode(); // optional, open log in debug mode, outputs messages to the console
    PerfSightAgent.InitContext("appid"); // required, please contact PerfSight to get AppId
    // ...
}

2. User Identification (Required)

public static void SetUserId(string openId)

Function: Set OpenId
openId: 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 PerfSightAgent.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. Mark Scene Start (Required)

public static void MarkLoadlevel(string 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, PerfSightAgent.MarkLoadlevel("SceneName") is called before the Application.LoadLevel function in Unity.

4. Mark Scene Loading Completion (Optional)

public static void MarkLoadlevelCompleted()

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

After a scene is loaded, PerfSightAgent.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 PerfSightAgent.MarkLoadlevelCompleted() is called several times within the scene(MarkLeveLoad to MarkLevelFin), only the first call takes effect.

5. Mark the end of the scene(Required)

public static void MarkLevelFin()

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

PerfSightAgent.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 PerfSightAgentt.MarkLevelFin() is not called at the end of a scene, the next PerfSightAgent.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.

6. Sub-Scene Marking (Optional)

Sometimes we need to pay attention to the performance of some special regions of the scene, such as group battles or PVE battles with bosses, or we need to exclude their performance data so as not to affect the overall performance data.

6.1 Tag (Optional)

public static void BeginTag(string tagName)

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

public 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.

6.2 Region Exclusion (Optional)

public 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.

exclude

7. Network Latency Reporting (Optional)

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 PerfSightAgent.PostNetworkLatency() interface.

public static void PostNetworkLatency(int latency)

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

IEnumerator UpdateNetworkLatency()
    {
        while (true)
        {
			//detect network latency on the client side
            PerfSightAgent.PostNetworkLatency(ntl);
            yield return new WaitForSeconds(1f);
        }
 }

PerfSight Server performs statistical analysis of the uploaded latency data from multiple dimensions such as region, scene, and cellular network type.

8. 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.

public 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. qualitysetting

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);

9. Custom Version Number Setting

（Android/iOS Optional）

public static void SetVersionIden(string version)

Function: Set custom version number
version: 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(string version)

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

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

10. Dyeing Event Reporting (Optional)

public static void PostEvent(int key, string value)

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.

11.Key-Value Data Reporting (Optional)

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();

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:

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.

13. 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.

PerfSightAgent.SetPCServerURL(reporting domain name);

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

14. Build Requirements

For iOS builds, please additionally configure the following content:
In Xcode Target > General > Frameworks, Libraries, and Embedded Content, add the dependent libraries libz.tdb, libc++.tbd, libresolv.tbd, MetricKit.framework, SystemConfiguration.framework, UIKit.framework, and CoreTelephony.framework, where MetricKit.framework is weakly linked, as shown in the figure below.
qcc1
qcc1

15. 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.

Unity Integration Guide

1. Initialization (Required)​

2. User Identification (Required)​

3. Mark Scene Start (Required)​

4. Mark Scene Loading Completion (Optional)​

5. Mark the end of the scene(Required)​

6. Sub-Scene Marking (Optional)​

6.1 Tag (Optional)​

6.2 Region Exclusion (Optional)​

7. Network Latency Reporting (Optional)​

8. Custom Quality Information (Optional)​

9. Custom Version Number Setting​

（Android/iOS Optional）​

（Windows Required）​

10. Dyeing Event Reporting (Optional)​

11.Key-Value Data Reporting (Optional)​

13. PerfSight Reporting Configuration​

Android Configuration​

iOS Configuration​

Windows Configuration​

14. Build Requirements​

15. Debugging​

Android​

iOS​

Windows​