This module provides risk control detection capabilities based on application risk factors. It receives multi-dimensional risk factor data collected from the application side and performs comprehensive risk assessments using the predefined risk control policies, helping apps achieve device security risk identification and control.
Since: 26.0.0
type ValueType = number | boolean | string
Defines the type for factor data values. The value can be a Boolean value, a number, or a string.
Atomic service API: This API can be used in atomic services since API version 26.0.0.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.Security.SafetyDetect
Since: 26.0.0
| Type | Description |
|---|---|
| number | The value can be any number. |
| boolean | The value is of the Boolean type. |
| string | The value can be any string. |
App risk factor data.
Atomic service API: This API can be used in atomic services since API version 26.0.0.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.Security.SafetyDetect
Since: 26.0.0
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| factorName | string | No | No | Factor name, which contains 1 to 255 bytes. |
| factorValue | ValueType | No | No | Factor value. |
Imports app risk factor data.
Atomic service API: This API can be used in atomic services since API version 26.0.0.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.Security.SafetyDetect
Since: 26.0.0
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| appFactorData | Array<AppFactorData> | No | No | List of risk data used for risk control calculation. The maximum array length is 50. |
| nonce | string | No | No | A nonce value used to identify a calculation session, with a length of 16 to 66 bytes. |
Request parameter for risk control scoring.
Atomic service API: This API can be used in atomic services since API version 26.0.0.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.Security.SafetyDetect
Since: 26.0.0
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| policyName | string | No | No | Risk policy name, which contains 1 to 255 bytes. |
| nonce | string | No | No | A nonce value used to identify a calculation session, with a length of 16 to 66 bytes. |
Return object for a risk control scoring request.
Atomic service API: This API can be used in atomic services since API version 26.0.0.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.Security.SafetyDetect
Since: 26.0.0
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| result | string | No | No | JWS-format string encoded using Base64URL. If an exception or error occurs, an error code will be returned. |
importRiskFactors(data: ImportData): Promise<void>
Imports app-level risk factor data. This API uses a promise to return the result.
Atomic service API: This API can be used in atomic services since API version 26.0.0.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.Security.SafetyDetect
Device behavior difference: This API applies to a narrower range of device types (phones, PCs/2-in-1 devices, and tablets) than the underlying system capability (phones, PCs/2-in-1 devices, tablets, and wearables). Due to device capability limitations, calling this API on wearables will return error code 801.
Since: 26.0.0
Parameters:
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data | ImportData | Yes | App risk factor data to import. |
Returns:
| Type | Description |
|---|---|
| Promise<void> | Promise that returns no value. |
Error codes:
For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.
| ID | Error Message |
|---|---|
| 801 | API is not supported. |
| 1010800004 | Verify capability fail. |
| 1010800005 | The number of calls exceeds the parallel threshold. |
| 1010800006 | The invoking frequency exceeds the threshold. |
| 1010800007 | Operation timeout. |
| 1010800009 | Failed to import risk factor data. |
Example:
import { riskControlEngine } from '@kit.DeviceSecurityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { cryptoFramework } from '@kit.CryptoArchitectureKit';
import { util } from '@kit.ArkTS';
const TAG = 'riskControlEngineJsTest';
let rand = cryptoFramework.createRandom();
let len = 32;
let randData = rand.generateRandomSync(len);
let base64 = new util.Base64Helper();
// Import app risk factor data.
let data: riskControlEngine.ImportData = {
appFactorData: [
{ factorName: 'factor_1', factorValue: 3600 },
{ factorName: 'factor_2', factorValue: false }
],
nonce: base64.encodeToStringSync(randData.data) // Random number of 16 to 66 bytes
};
try {
hilog.info(0x0000, TAG, 'ImportRiskFactors begin.');
await riskControlEngine.importRiskFactors(data);
hilog.info(0x0000, TAG, 'Succeeded in importRiskFactors.');
} catch (err) {
let e: BusinessError = err as BusinessError;
hilog.error(0x0000, TAG, 'ImportRiskFactors failed: %{public}d %{public}s', e.code, e.message);
} getRiskControlResult(req: RiskControlDetectionRequest): Promise<RiskControlDetectionResponse>
Obtains the risk control scoring result. This API uses a promise to return the result.
Atomic service API: This API can be used in atomic services since API version 26.0.0.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.Security.SafetyDetect
Device behavior difference: This API applies to a narrower range of device types (phones, PCs/2-in-1 devices, and tablets) than the underlying system capability (phones, PCs/2-in-1 devices, tablets, and wearables). Due to device capability limitations, calling this API on wearables will return error code 801.
Since: 26.0.0
Parameters:
| Name | Type | Mandatory | Description |
|---|---|---|---|
| req | RiskControlDetectionRequest | Yes | Request parameter for risk control scoring. |
Returns:
| Type | Description |
|---|---|
| Promise<RiskControlDetectionResponse> | Promise used to return the risk control result. |
Error codes:
For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.
| ID | Error Message |
|---|---|
| 801 | API is not supported. |
| 1010800004 | Verify capability fail. |
| 1010800005 | The number of calls exceeds the parallel threshold. |
| 1010800006 | The invoking frequency exceeds the threshold. |
| 1010800007 | Operation timeout. |
| 1010800010 | Risk score calculation failed. |
Example:
import { riskControlEngine } from '@kit.DeviceSecurityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { cryptoFramework } from '@kit.CryptoArchitectureKit';
import { util } from '@kit.ArkTS';
const TAG = 'riskControlEngineJsTest';
let rand = cryptoFramework.createRandom();
let len = 32;
let randData = rand.generateRandomSync(len);
let base64 = new util.Base64Helper();
const request: riskControlEngine.RiskControlDetectionRequest = {
policyName: 'Policy_1001', // Risk policy.
nonce: base64.encodeToStringSync(randData.data) // Random number of 16 to 66 bytes
};
try {
hilog.info(0x0000, TAG, 'Getting risk control result begin.');
const response: riskControlEngine.RiskControlDetectionResponse =
await riskControlEngine.getRiskControlResult(request);
// The result is in JWS format and needs to be parsed and verified according to the specifications.
hilog.info(0x0000, TAG, 'Risk control result: %{public}s', response.result);
} catch (err) {
const e: BusinessError = err as BusinessError;
hilog.error(0x0000, TAG, 'Get risk control result failed: %{public}d %{public}s', e.code, e.message);
}