• 1. Cloud-Control File Definition
    • 1.1 Overall Structure
    • 1.2 Configuration Domain Definition
  • 2. Device Level Determination Process
  • 3. Integration
  • 3.1 Unreal Engine
    • 3.1.1 iOS Platform
    • 3.1.2 Android Platform
  • 3.2 Unity Engine
  • 4. Update Configuration File

Cloud-Controlled Device Level Classification

The cloud-controlled device level classification function can quickly implement device level classification for Android and iOS, and supports Unity and Unreal engines. PerfSight (APM) provides default device level classification configuration files, and businesses can fine-tune them according to their actual needs.

Unity interface： 
int CheckDeviceClass(string domainName)
int CheckDeviceClassByString(string domainName, string json)//determine the level of the device by passing in a json string

Unreal interface：

//iOS
int GetDeviceLevelByQcc(const char* domainName, const char* fileDir);
int GetDeviceLevelByString(const char* domainName,const char* json);//determine the level of the device by passing in a json string

//Android
int GetDeviceLevelByQcc(const char* domainName, const char* gpuFamily);// gpuFamily is the model of the GPU
int GetDeviceLevelByString(const char* domainName, const char* gpuFamily, const char* json);//determine the level of the device by passing in a json string

1. Cloud-Control File Definition

1.1 Overall Structure

The cloud-control file is defined in JSON format, and the overall structure is shown in the following figure. qcc1 The cloud-control file macroscopically includes three parts, namely the link version number definition, the configuration domain list definition, and the configuration domain definition. Multiple configuration domain definitions can be included in the same cloud-control file, and each configuration domain is isolated. When calling the CheckDeviceClass(const char* domain) interface for judgment, the specified configuration domain name is passed in for rule judgment.

Link Version Number:：JSON numeric type (text type will be supported later). The SDK will download the latest configuration file from the cloud based on this version number when initializing the cloud-control function, so it is named "link version number".For example, a default configuration file is included in the installation package, and the link version number is version1. After the business initializes the cloud-control function, the SDK will actively download the configuration file version1 from the cloud-control.

Configuration Domain List：JSON string type, which defines the specific configuration domains in this configuration file. It is also the name that needs to be passed in the CheckDeviceClass(const char* domain) function.

Configuration Domain：JSON object type. The key is the name defined in the "configuration domain list", and the value is the specific definition (which will be explained in detail in the next section). Each name defined in the "configuration domain list" needs to have a corresponding configuration domain definition.

Due to the slight differences in the definition of "configuration domains" for Android and iOS, two separate configuration files are required for Android and iOS platforms.


1.2 Configuration Domain Definition

The "configuration domain" definition for Android and iOS is slightly different. Due to fragmentation issues on Android, multiple configuration items are set, including the definition of device level classification, detailed level classification, overall control switch definition, judgment dimension switch definition, regular expression switch, emulator level switch, whitelist definition, and interval threshold judgment definition. iOS only has the configuration of device level classification, detailed level classification, regular expression switch, device whitelist, and SoC whitelist.

1.2.1 Device Level Classification: JSON numeric type, indicating the number of levels. For example,

1.2.2 Detailed Level Classification: JSON array (integer array), indicating the detailed level values. There are a total of elements in the array, such as[C1,C2…,Cm]. Note: It is recommended that C1>=1， and 0 is a reserved level. When an internal error occurs, the device level classification returned is 0.

1.2.3 Default Level:JSON numeric type. If only the whitelist is configured and there is no configuration for interval threshold judgment, the value returned when there is no match in the whitelist.

1.2.4 Emulator Level:Deprecated. The accuracy of client-determined emulators is not high, so it is deprecated.

1.2.5 Control Switch: It is divided into overall control switch（switchops）and interval threshold judgment switch（andopts）, both of which are JSON numeric types used to control whether each module is enabled. Only the enabled modules will participate in the rule judgment, otherwise they will be ignored (iOS platform does not have this item). The overall control switch is used to control the matching strategy of the whitelist and the interval threshold judgment. The "whitelist" switch is mainly used to control whether the device whitelist, GPU whitelist, SoC whitelist, and manufacturer whitelist are effective. The interval threshold judgment switch is mainly used to control whether the resolution interval judgment dimension, memory interval judgment dimension, CPU interval judgment frequency dimension, CPU core number interval judgment dimension, and GPU interval judgment dimension are effective.

The control switch is defined based on the "bit" operation. The value of each switch bit is：

  1. The switch value of the model whitelist is 21
  2. The switch value of the GPU whitelist is 22
  3. The switch value of the SoC whitelist is 23
  4. The switch value of the manufacturer whitelist is 24
  5. The switch value of the resolution (Deprecated) interval threshold judgment dimension is 25
  6. The switch value of the memory interval threshold judgment is 26
  7. The switch value of the CPU frequency interval threshold judgment is 27
  8. The switch value of the CPU core number interval threshold judgment is 28
  9. The switch value of the GPU dimension interval threshold judgment is 29

When you need to enable the corresponding judgment dimension, add it to the "AND" operation. For example, if you need to enable the functions of the model whitelist, GPU whitelist, memory interval threshold judgment, and GPU dimension interval threshold judgment, then switchops = 21 | 22 | 26 | 29 = 582, andopts = 26 | 29 = 576。

1.2.6 Regular expression switch regex：JSON numeric type, 0 means off, 1 means on, can be used to configure the whitelist based on regular expressions,

1.2.7 Whitelist judgment rules:Provide whitelist matching rules based on model name, GPU model, SoC model, and manufacturer model. . The whitelist provides three string matching rules, ：

  1. Exact matching: The model information must match the configuration item information exactly (case-insensitive).
  2. Prefix matching: When the last character of an item in the whitelist is *, prefix matching will be enabled (if the model information begins with this configuration item, it will hit this rule). This is mainly used for some Samsung phones, which have different names when they are released in different regions, but the prefixes are the same. For example, if the model whitelist is configured as SM-G950*, and the current model name is SM-G9501 or SM-G9502, it will hit this rule.
  3. Regular expression matching: When the regex switch is turned on, all strings in the whitelist will use regular expression rules for matching.

iOS's whitelist only supports model whitelist and SoC whitelist. For model information, the interface provided by iOS can only obtain the internal code name, such as iPhone9,1, iPhone5,4, while the external code name, such as iPhone XS Max, iPhone 12, cannot be obtained. PerfSight SDK has established a mapping relationship between internal and external code names by default, so the model whitelist supports the configuration of models with internal and external code names.

1.2.8 Dimension interval threshold judgment rules: In the case where the whitelist cannot meet the requirements, a general judgment model based on mathematical segmentation rules is provided. The dimension interval threshold judgment supports five dimensions of segmented threshold judgment: 1. Resolution judgment interval threshold (taking the width of the screen, ); 2、Memory judgment interval threshold (unit: MiB); 3、 CPU frequency judgment interval threshold (maximum frequency of CPU core,); 4. CPU core number judgment interval threshold; 5. GPU judgment interval threshold. These five dimensions of segmented judgment can be selectively enabled based on the "interval threshold judgment switch bit".

Resolution judgment interval threshold, memory judgment interval threshold, CPU frequency judgment interval threshold, CPU core number judgment interval threshold. Only one threshold array definition is required for these four dimensions, as follows:

Define the number of model levels as , and the detailed model levels are [C1,C2…,Cm].Therefore, threshold values need to be defined for each dimension control, that is, [T1,T2…,Tm-1] and T1<=T2…<=Tm-1（monotonically increasing）.

Define the current dimension value t
If t < T1， the current model level for this dimension is C1
If t >= Tm-1,the model level for this dimension is Cm
If t >= Tn and t < Tn+1, the model level for this dimension is Cn

For example, if the number of model levels is m=3, the detailed model levels are [1,2,3], and the memory judgment interval threshold is [2499, 3499], if the current model's memory is 3000MiB, because 3000 > 2499 and 3000 < 3499, the model level for the current model on the memory dimension is 2.

GPU segmented threshold judgment: According to statistics, the mainstream brands of GPU models on the Android platform are Adreno, Mali, PowerVR, and Tegra. For different brands of GPUs, their model names have strict specifications, which also represent different performance levels of the chips. Therefore, the different levels of GPU can be divided into different segments based on naming rules.

  1. For Adreno brand GPU models, the uniform naming rule is Adreno (tm) N,where N is its specific integer model, mainly divided into 100 series, 200 series, 300 series, 400 series, 500 series.
  2. For Mali brand, the uniform naming rule is Mali-SN, where S is the specific series, and N is the model, mainly g series and t series
  3. For PowerVR brand, the uniform naming rule is PowerVR-SN, where S is the specific series, and N is the model, mainly sgx series, gt series, ge series, gx series, g series
  4. For Tegra brand, the uniform naming rule is Tegra-S, where S is the specific series, mainly K1, X1 series, 2 series, 3 series, 4 series

Considering the expandability of various brand GPU series, the series of sub-models participating in the operation need to be specified when defining GPUs: series, and new sub-series can be easily added if necessary.

For example, if the number of model levels is m=3, the detailed model levels are [1,2,3], and the GPU is defined based on Adreno as follows:

"gpu_vendor":{
   "adreno":{
      "series":["100","200","300","400","500"],
      "100":[199,200],
      "200":[299,299],
      "300":[330,399],
      "400":[430,499],
      "500":[520,521]
    }
}

If the current model's GPU model is Adreno (TM) 530, because 530 belongs to the 500 series and 530>521, the model level returned by the GPU dimension is 3.

1.2.9 Comprehensive judgment rule：barrel principle, taking the minimum value of multiple dimensions. Define the resolution dimension level return value as C1, the memory dimension level return value as C2, the CPU core number dimension level return value as C3, the CPU frequency dimension level return value as C4, and the GPU dimension level return value as C5. Then the final model level returned for the current device is C=min(C1,C2,C3,C4,C5)。

The overall cloud control configuration is defined as follows:

Android

{
   "version": versionnumber,
   "configureList": ["configname1",…"confignameN"],
   "configname1": {
   "classLevelNum": M,
   "classLevelValues": [C1,C2…,CM],
   "defLevel": C1 ,
   "switchops": S1,
   "regex": 0
   "andopts": S2,
   "emulator": , C1
   "filter-model": {"C1": ["model1","model2"],… "CM": ["model1"," model2"]},
   "filter-gpu": {"C1": ["gpu1","gpu2"],… "CM": ["gpu1"," gpu2"]},
   "filter-soc": {"C1": ["soc1","soc2"],… "CM": ["soc1","soc2"]},
   "filter-manu": {"C1": ["manu1","manu2"],… "CM": ["manu1","manu2"]},
   "resolution":[T1,T2…TM-1],
   "ram": [T1,T2…TM-1],
   "cpufreq": [T1,T2…TM-1],
   "cpucores": [T1,T2…TM-1],
   "gpu_vendor": {
   	"adreno": {
   		"series": ["100", "200", "300", "400", "500"],
   		"100": [T1,T2…TM-1], "200": [T1,T2…TM-1],
   		"300": [T1,T2…TM-1], "400": [T1,T2…TM-1],
   		"500": [T1,T2…TM-1]
   	},"mali": {
   		"series": ["g", "t"],
   		"g": [T1,T2…TM-1], "t":[T1,T2…TM-1]
   	},
   	"powervr": {
   		"series": ["sgx", "gt", "ge", "gx", "g"],
   		"sgx": [T1,T2…TM-1], "gt":[T1,T2…TM-1],
   		"ge": [T1,T2…TM-1], "gx": [T1,T2…TM-1],
   		"g":[T1,T2…TM-1]
   	},
   	"tegra": {
   		"series": ["k1", "x1", "2", "3", "4"],
   		"k1": [T1,T2…TM-1], "x1":[T1,T2…TM-1],
   		"2": [T1,T2…TM-1], "3": [T1,T2…TM-1],
   		"4": [T1,T2…TM-1]
   	}
   }
   },…
   "confignameN": {}
}

iOS

{
	"version": 2, 
	"regex":1, 
	"configureList": ["level3", "level2"],  
	"level3": {
		"classLevelNum": 3,     
		"classLevelValues": [2, 4, 8], 
		"defLevel": 2,  
		"filter-model": {
			"2": ["iPhone11,4", "iPhone XS Max, "iPhone10,6", "iPhone SE.*","iPhone 8 Plus"],
			"4": ["iPad6,12"],
			"8": ["iPhone3,2"]
		}
	},
	"level2": {
		"classLevelNum": 3,
		"regex":1,
		"classLevelValues": [2, 4, 8],
		"defLevel": 4,
		"filter-model": {
			"4": ["iPhone XS Max", "iPhone XS.*", "iPhone 8.*", "iPhone9,4", "iPhone8,4"],
			"8": ["iPhone 7[A10]"],
			"2": ["iPhone3,2"]
		}
	}
}

2. Device Level Determination Process

For a single configuration domain, the specific model level value will be calculated based on the whitelist switch and interval threshold judgment switch. In the whitelist judgment, the "short-circuit rule" is used, that is, once a match is found, the function immediately returns. which is to first judge the model whitelist, then the GPU whitelist, then the SoC whitelist, and finally the manufacturer whitelist. According to statistical analysis, the model coverage dimension is the smallest, while the manufacturer coverage dimension is the largest, and the granularity of coverage gradually increases.

If there is no match in the whitelist, the final model level information will be obtained based on the interval threshold judgment. If the interval threshold is not configured and only the whitelist control is used, and the whitelist is not matched, the default model level value configuration will be returned.

3. Integration

Due to the different processing methods of external resource files for the Unreal and Unity engines and the Android and iOS platforms, they are explained separately.

3.1 Unreal Engine

The configurations for the iOS and Android platforms are slightly different, so they are introduced separately.

3.1.1 iOS Platform

  1. Rename the default model configuration file as QCC_{appId}_IOS (replace appId with the platform's ID, such as 67895, QCC_67895_IOS)
  2. Create a new folder in the project directory Content, such as tapmdir, with any name and path
  3. Put the default model configuration file into the folder created in step 2, such as: ${ProjRootDir}/Content/tapmdir/QCC_{appId}_IOS
  4. In the UE4 Editor settings, search for Additional Non-Asset Directories To Copy and click to add the newly created folder tapmdir

Steps 2, 3, and 4 can be changed according to the actual project.

FString tapmdirPath = FPaths::ProjectContentDir() + FString(TEXT("tapmdir")); int deviceLevel = GetDeviceLevelByQcc("level2", TCHAR_TO_UTF8(*tapmdirPath));

3.1.2 Android Platform

Place the default cloud control model level configuration file in the following path: ${Plugins}\GPM(PerfSight)\Source\GPMSDKLib(PerfSightSDKLib)\Android\assets. If there is no assets folder, you need to create one. Rename the default configuration file as QCC_appId, for example, QCC_67895.

int GetDeviceLevelByQcc("level2", const char* gpuFamily); // gpuFamily is the GPU model.

3.2 Unity Engine

Place the default model level configuration in the StreamingAssets directory. The naming convention for the default configuration file on iOS is QCC_{appId}_IOS, and on Android is QCC_{appId}.

int CheckDeviceClass(string domainName)

4. Update Configuration File

The cloud control configuration file can be updated in China based on https://tapm.wetest.qq.com/cloudFile 或者 https://perfsight.qq.com/cloudFile ,and in overseas based on https://tapm.wetest.net/cloudFile.

The update logic on the SDK side is as follows:
  1. After installing the game package, the first time the GetDeviceByQcc/CheckDeviceClass interface is called to obtain the model level, it will use the default configuration file on the local device to parse and obtain the level value.
  2. In a game process startup, the first time the GetDeviceByQcc/CheckDeviceClass interface is called, it will asynchronously request the cloud-side configuration file and save it to the local device as the "current configuration file". Subsequent calls to the GetDeviceByQcc/CheckDeviceClass interface during the local device startup process will not parse the "current configuration file" but instead use the cached value from the first call to the GetDeviceByQcc/CheckDeviceClass interface.
  3. Starting from the second time the game is launched (not the first time after installation), the "current configuration file" obtained in the previous launch will be used for configuration parsing and return. If the "current configuration file" parsing fails, the default configuration file packaged with the game will be used for parsing and return.

If the business does not need the PerfSight SDK to actively pull the cloud-side configuration file, the CheckDeviceClassByString/CheckDeviceLevelByString interface can be used to pass the configuration file content that needs to be parsed to the SDK for parsing, so that the SDK will not request the cloud-side configuration file.

The default cloud control configuration file is stored in the CDN network of the PerfSight. If the business party needs it (for compliance or update convenience), the configuration file can be placed in the business party's own CDN network, as follows:

The default cloud control configuration file is stored in the CDN network of the PerfSight. If the business party needs it (for compliance or update convenience), the configuration file can be placed in the business party's own CDN network, as follows:

Android

<meta-data android:name="APM_QCC_URL" android:value="Custom CDN address"/>

iOS

The CDN of the iOS platform can be configured through Info.plist or AdditionalPlistData

<key>GPM or APM</key>
<dict>
   <key>apm_cc_url</key>
   <string>Custom CDN address</string>
</dict>
Last Updated: