输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
文档管理中心

HarmonyOS

输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
API参考
高级筛选
API version全部版本
设备全部
元服务API集不筛选
您当前正在浏览HarmonyOS最新文档，覆盖已发布的所有API版本，可在API参考中筛选您使用的API版本。详细的版本配套关系请参考版本说明。
API参考系统安全Device Security Kit（设备安全服务）ArkTS APISafetyDetect（安全检测）

SafetyDetect（安全检测）

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+Wearable5.1.0(18)+
更新时间: 2026-09-09 06:54
本文导读
展开章节

安全检测模块提供设备环境安全检测能力，包括系统完整性检测、恶意URL检测、统一风控凭证等安全评估功能。开发者应用可基于检测结果评估设备安全风险并采取相应防护措施。

起始版本： 5.0.0(12)

导入模块

收起
自动换行
深色代码主题
复制
  1. import { safetyDetect } from '@kit.DeviceSecurityKit';

SysIntegrityRequest

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+Wearable5.1.0(18)+

系统完整性检测的请求参数。

元服务API： 从API版本5.0.2(14)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Security.SafetyDetect

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 5.0.0(12)

展开
名称 类型 只读 可选 说明
nonce string 否 否 开发者应用传入的一个随机生成的nonce值，用于防重放攻击，每个请求应具有唯一性，在检测结果中会包含该值。nonce必须是长度16至66字节之间，有效值为base64编码范围。

SysIntegrityResponse

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+Wearable5.1.0(18)+

系统完整性检测返回值。

元服务API： 从API版本5.0.2(14)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Security.SafetyDetect

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 5.0.0(12)

展开
名称 类型 只读 可选 说明
result string 否 否 JWS格式的系统完整性检测结果。JWS内容详见系统完整性检测开发步骤。

UrlCheckRequest

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+Wearable5.1.0(18)+

URL检测请求参数。

元服务API： 从API版本5.0.2(14)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Security.SafetyDetect

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 5.0.0(12)

展开
名称 类型 只读 可选 说明
urls Array<string> 否 否 被检测的URL列表。URL数量最多10个并且每个URL长度不大于4096字节。

UrlCheckResponse

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+Wearable5.1.0(18)+

URL检测返回值。

元服务API： 从API版本5.0.2(14)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Security.SafetyDetect

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 5.0.0(12)

展开
名称 类型 只读 可选 说明
results Array<UrlCheckResult> 否 否 URL检测返回的检测结果。每个结果包含被检查的URL及其威胁类型。

UrlCheckResult

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+Wearable5.1.0(18)+

URL检测结果详情。

元服务API： 从API版本5.0.2(14)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Security.SafetyDetect

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 5.0.0(12)

展开
名称 类型 只读 可选 说明
url string 否 否 对应到输入参数中被检测的URL。
threat UrlThreatType 否 否 URL的威胁类型。

UrlThreatType

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+Wearable5.1.0(18)+

枚举URL威胁类型。

元服务API： 从API版本5.0.2(14)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Security.SafetyDetect

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 5.0.0(12)

展开
名称 值 说明
NORMAL 0 未发现威胁。
MALWARE 1 恶意类型的URL。
PHISHING 2 钓鱼类型的URL。
OTHERS 3 其他威胁类型的URL。

safetyDetect.checkSysIntegrity

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+Wearable5.1.0(18)+

checkSysIntegrity(req: SysIntegrityRequest): Promise<SysIntegrityResponse>

获取本设备的系统完整性的在线检测结果。使用Promise异步回调。

注意

该接口涉及端云协同，需要联网等耗时操作，因此不要在UI线程中执行，避免阻塞UI线程。

元服务API： 从API版本5.0.2(14)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Security.SafetyDetect

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 5.0.0(12)

参数：

展开
参数名 类型 必填 说明
req SysIntegrityRequest 是

请求参数，包含nonce。

nonce长度必须16至66字节之间，有效值为base64编码范围。

返回值：

展开
类型 说明
Promise<SysIntegrityResponse> Promise对象，返回系统完整性检测结果。

错误码：

以下错误码的详细介绍请参见ArkTS API错误码。

展开
错误码ID 错误信息
201 Permission denied.
401

Invalid parameters.

Possible causes:

1. Mandatory parameters are left unspecified.

2. Incorrect parameter types.

3. Parameter verification failed.
801

API is not supported.

适用版本：5.1.0(18)+
1010800001 Internal error.
1010800002 The network is unreachable.
1010800003 Access cloud server fail.
1010800005

The number of calls exceeds the parallel threshold.

适用版本：5.1.0(18)+
1010800006

The invoking frequency exceeds the threshold.

适用版本：5.1.0(18)+
1010800007

Operation timeout.

适用版本：5.1.0(18)+
1010800008

The cloud service traffic exceeds the threshold.

适用版本：5.1.0(18)+

示例：

收起
自动换行
深色代码主题
复制
  1. import { safetyDetect } from '@kit.DeviceSecurityKit';
  2. import { BusinessError} from '@kit.BasicServicesKit';
  3. import { hilog } from '@kit.PerformanceAnalysisKit';
  4. 

  5. const TAG = 'SafetyDetectJsTest';
  6. 

  7. // 请求系统完整性检测，并处理结果
  8. let req : safetyDetect.SysIntegrityRequest = {
  9.   nonce : 'imEe1PCRcjGkBCAhOCh6ImADztOZ8ygxlWRs' // 从服务器生成的随机的nonce值
  10. };
  11. try {
  12.   hilog.info(0x0000, TAG, 'CheckSysIntegrity begin.');
  13.   const data: safetyDetect.SysIntegrityResponse = await safetyDetect.checkSysIntegrity(req);
  14.   hilog.info(0x0000, TAG, 'Succeeded in checkSysIntegrity: %{public}s', data.result);
  15. } catch (err) {
  16.   let e: BusinessError = err as BusinessError;
  17.   hilog.error(0x0000, TAG, 'CheckSysIntegrity failed: %{public}d %{public}s', e.code, e.message);
  18. }

safetyDetect.checkUrlThreat

Phone5.0.0(12)+PC/2in15.0.1(13)+Tablet5.0.0(12)+Wearable5.1.0(18)+

checkUrlThreat(req: UrlCheckRequest): Promise<UrlCheckResponse>

检测URL是否为恶意网址。使用Promise异步回调。

注意

该接口涉及端云协同，需要联网等耗时操作，因此不要在UI线程中执行，避免阻塞UI线程。

元服务API： 从API版本5.0.2(14)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Security.SafetyDetect

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 5.0.0(12)

参数：

展开
参数名 类型 必填 说明
req UrlCheckRequest 是

请求参数，包含被检测的URL列表。

传入的URL数量最多10个并且每个URL长度不大于4096字节。

返回值：

展开
类型 说明
Promise<UrlCheckResponse> Promise对象，返回URL检测结果。

错误码：

以下错误码的详细介绍请参见ArkTS API错误码。

展开
错误码ID 错误信息
201 Permission denied.
401

Invalid parameters.

Possible causes:

1. Mandatory parameters are left unspecified.

2. Incorrect parameter types.

3. Parameter verification failed.
801

API is not supported.

适用版本：5.1.0(18)+
1010800001 Internal error.
1010800002 The network is unreachable.
1010800003 Access cloud server fail.
1010800005

The number of calls exceeds the parallel threshold.

适用版本：5.1.0(18)+
1010800006

The invoking frequency exceeds the threshold.

适用版本：5.1.0(18)+
1010800007

Operation timeout.

适用版本：5.1.0(18)+
1010800008

The cloud service traffic exceeds the threshold.

适用版本：5.1.0(18)+

示例：

收起
自动换行
深色代码主题
复制
  1. import { safetyDetect } from '@kit.DeviceSecurityKit';
  2. import { BusinessError} from '@kit.BasicServicesKit';
  3. import { hilog } from '@kit.PerformanceAnalysisKit';
  4. 

  5. const TAG = 'SafetyDetectJsTest';
  6. 

  7. // 请求URL检测，并处理结果
  8. let req : safetyDetect.UrlCheckRequest = {
  9.   urls : ['https://test1.com']
  10. };
  11. try {
  12.   hilog.info(0x0000, TAG, 'CheckUrlThreat begin.');
  13.   const data: safetyDetect.UrlCheckResponse = await safetyDetect.checkUrlThreat(req);
  14.   hilog.info(0x0000, TAG, 'Succeeded in checkUrlThreat: %{public}s %{public}d', data.results[0].url, data.results[0].threat);
  15. } catch (err) {
  16.   let e: BusinessError = err as BusinessError;
  17.   hilog.error(0x0000, TAG, 'CheckUrlThreat failed: %{public}d %{public}s', e.code, e.message);
  18. }

safetyDetect.checkSysIntegrityOnLocal

Phone5.1.0(18)+PC/2in15.1.0(18)+Tablet5.1.0(18)+Wearable5.1.0(18)+

checkSysIntegrityOnLocal(): Promise<string>

获取本设备的系统完整性的本地检测结果。使用Promise异步回调。

元服务API： 从API版本5.1.0(18)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Security.SafetyDetect

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 5.1.0(18)

返回值：

展开
类型 说明
Promise<string> Promise对象，返回JSON格式的本地系统完整性检测结果，格式详见本地系统完整性检测结果JSON结构说明。

本地系统完整性检测结果JSON结构说明：

展开
字段名 类型 说明
basicIntegrity boolean 本地系统完整性检测的结果。true表示检测结果完整，false表示存在风险。
detail Array<string> 可选字段，当basicIntegrity结果为false时，该字段将提供存在风险的原因。取值见detail字段取值说明。

detail字段取值说明：

展开
值 说明
jailbreak 设备被越狱。
emulator 非真实设备。
attack 设备被攻击。
unlock 设备被解锁。

示例（返回值）：

收起
自动换行
深色代码主题
复制
  1. {
  2.   "basicIntegrity": false,
  3.   "detail": [
  4.     "attack",
  5.     "jailbreak",
  6.     "emulator"
  7.   ]
  8. }

错误码：

以下错误码的详细介绍请参见ArkTS API错误码。

展开
错误码ID 错误信息
801 API is not supported.
1010800001 Internal error.
1010800004 Verify capability fail.
1010800005 The number of calls exceeds the parallel threshold.
1010800006 The invoking frequency exceeds the threshold.
1010800007 Operation timeout.

示例：

收起
自动换行
深色代码主题
复制
  1. import { safetyDetect } from '@kit.DeviceSecurityKit';
  2. import { BusinessError} from '@kit.BasicServicesKit';
  3. import { hilog } from '@kit.PerformanceAnalysisKit';
  4. 

  5. const TAG = 'SafetyDetectJsTest';
  6. 

  7. // 请求本地系统完整性检测，并处理结果
  8. try {
  9.   hilog.info(0x0000, TAG, 'CheckSysIntegrityOnLocal begin.');
  10.   const result: string = await safetyDetect.checkSysIntegrityOnLocal();
  11.   hilog.info(0x0000, TAG, 'Succeeded in checkSysIntegrityOnLocal: %{public}s', result);
  12. } catch (err) {
  13.   let e: BusinessError = err as BusinessError;
  14.   hilog.error(0x0000, TAG, 'CheckSysIntegrityOnLocal failed: %{public}d %{public}s', e.code, e.message);
  15. }

safetyDetect.checkSysIntegrityEnhanced

Phone6.0.0(20)+PC/2in16.0.0(20)+Tablet6.0.0(20)+Wearable6.0.0(20)+

checkSysIntegrityEnhanced(req: SysIntegrityRequest): Promise<SysIntegrityResponse>

获取本设备的系统完整性的在线增强检测结果。使用Promise异步回调。

注意

该接口涉及端云协同，需要联网等耗时操作，因此不要在UI线程中执行，避免阻塞UI线程。

元服务API： 从API版本6.0.0(20)开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Security.SafetyDetect

模型约束： 此接口仅可在Stage模型下使用。

起始版本： 6.0.0(20)

参数：

展开
参数名 类型 必填 说明
req SysIntegrityRequest 是

请求参数，包含nonce。

nonce长度必须16至66字节之间，有效值为base64编码范围。

返回值：

展开
类型 说明
Promise<SysIntegrityResponse> Promise对象，返回系统完整性增强检测结果。

错误码：

以下错误码的详细介绍请参见ArkTS API错误码。

展开
错误码ID 错误信息
801 API is not supported.
1010800001 Internal error.
1010800002 The network is unreachable.
1010800003 Access cloud server fail.
1010800004 Verify capability fail.
1010800005 The number of calls exceeds the parallel threshold.
1010800006 The invoking frequency exceeds the threshold.
1010800007 Operation timeout.
1010800008 The cloud service traffic exceeds the threshold.

示例：

收起
自动换行
深色代码主题
复制
  1. import { safetyDetect } from '@kit.DeviceSecurityKit';
  2. import { BusinessError} from '@kit.BasicServicesKit';
  3. import { hilog } from '@kit.PerformanceAnalysisKit';
  4. 

  5. const TAG = 'SafetyDetectJsTest';
  6. 

  7. // 请求系统完整性增强检测，并处理结果
  8. let req : safetyDetect.SysIntegrityRequest = {
  9.   nonce : 'imEe1PCRcjGkBCAhOCh6ImADztOZ8ygxlWRs' // 从服务器生成的随机的nonce值
  10. };
  11. try {
  12.   hilog.info(0x0000, TAG, 'CheckSysIntegrityEnhanced begin.');
  13.   const data: safetyDetect.SysIntegrityResponse = await safetyDetect.checkSysIntegrityEnhanced(req);
  14.   hilog.info(0x0000, TAG, 'Succeeded in checkSysIntegrityEnhanced: %{public}s', data.result);
  15. } catch (err) {
  16.   let e: BusinessError = err as BusinessError;
  17.   hilog.error(0x0000, TAG, 'CheckSysIntegrityEnhanced failed: %{public}d %{public}s', e.code, e.message);
  18. }

RiskFactorType

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+

枚举风险因子类型。

元服务API： 从API版本26.0.0开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Security.SafetyDetect

模型约束： 此接口仅可在Stage模型下使用。

设备行为差异： 本接口实际支持的设备类型范围（Phone、PC/2in1、Tablet）小于其所属系统能力支持的设备类型范围（Phone、PC/2in1、Tablet、Wearable）。因设备能力受限，该接口在Wearable设备中调用将返回801错误码。

起始版本： 26.0.0

展开
名称 值 说明
HDC_DEBUG_STATE "hdcDebugState" HDC调试状态。
IS_DEVELOPER_MODE "isDeveloperMode" 开发者模式状态。
IS_VPN_STATUS "isVpnStatus" VPN状态。
IS_NET_PROXY_STATUS "isNetProxyStatus" 网络代理状态。
SIM_CNT "simCnt" 插入的SIM卡数量。
OOBE_CNT "oobeCnt" OOBE操作次数。
ODID_RESET_CNT "odidResetCnt" ODID重置次数。
ODID "odid" 当前ODID值。
IS_DISPLAY_CAPTURED "isDisplayCaptured" 屏幕录制状态。
GLOBAL_WINDOW_STATE "globalWindowState" 前台窗口模式。
BATTERY_CHARGE_STATE "batteryChargeState" 电池充电状态。
BATTERY_HEALTH_STATE "batteryHealthState" 电池健康状态。
ON_CALL_STATE "onCallState" 通话状态。

RiskFactorRequest

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+

风险因子查询请求参数。

元服务API： 从API版本26.0.0开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Security.SafetyDetect

模型约束： 此接口仅可在Stage模型下使用。

设备行为差异： 本接口实际支持的设备类型范围（Phone、PC/2in1、Tablet）小于其所属系统能力支持的设备类型范围（Phone、PC/2in1、Tablet、Wearable）。因设备能力受限，该接口在Wearable设备中调用将返回801错误码。

起始版本： 26.0.0

展开
名称 类型 只读 可选 说明
nonce string 否 否 开发者应用传入的一个随机生成的nonce值，用于防重放攻击，每个请求应具有唯一性，在检测结果中会包含该值。nonce必须是长度16至66字节之间，有效值为base64编码范围。
queries Array<FactorQuery> 否 否 要查询的风险因子列表。最大长度为20且不能为空。

FactorQuery

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+

风险因子查询项。

元服务API： 从API版本26.0.0开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Security.SafetyDetect

模型约束： 此接口仅可在Stage模型下使用。

设备行为差异： 本接口实际支持的设备类型范围（Phone、PC/2in1、Tablet）小于其所属系统能力支持的设备类型范围（Phone、PC/2in1、Tablet、Wearable）。因设备能力受限，该接口在Wearable设备中调用将返回801错误码。

起始版本： 26.0.0

展开
名称 类型 只读 可选 说明
factor RiskFactorType 否 否 要查询的风险因子类型。

RiskFactorResponse

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+

风险因子查询返回值。

元服务API： 从API版本26.0.0开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Security.SafetyDetect

模型约束： 此接口仅可在Stage模型下使用。

设备行为差异： 本接口实际支持的设备类型范围（Phone、PC/2in1、Tablet）小于其所属系统能力支持的设备类型范围（Phone、PC/2in1、Tablet、Wearable）。因设备能力受限，该接口在Wearable设备中调用将返回801错误码。

起始版本： 26.0.0

展开
名称 类型 只读 可选 说明
result string 否 否 JWS格式的风险因子查询结果。JWS内容详见统一风控凭证开发步骤。

safetyDetect.queryRiskFactors

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+

queryRiskFactors(req: RiskFactorRequest): Promise<RiskFactorResponse>

查询系统级风险因子数据。使用Promise异步回调。

元服务API： 从API版本26.0.0开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Security.SafetyDetect

模型约束： 此接口仅可在Stage模型下使用。

设备行为差异： 本接口实际支持的设备类型范围（Phone、PC/2in1、Tablet）小于其所属系统能力支持的设备类型范围（Phone、PC/2in1、Tablet、Wearable）。因设备能力受限，该接口在Wearable设备中调用将返回801错误码。

起始版本： 26.0.0

参数：

展开
参数名 类型 必填 说明
req RiskFactorRequest 是 风险因子查询请求参数。

返回值：

展开
类型 说明
Promise<RiskFactorResponse> Promise对象，返回风险因子查询结果。

错误码：

以下错误码的详细介绍请参见ArkTS API错误码。

展开
错误码ID 错误信息
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.
1010800011 Failed to query the risk factor.

示例：

收起
自动换行
深色代码主题
复制
  1. import { safetyDetect } from '@kit.DeviceSecurityKit';
  2. import { BusinessError} from '@kit.BasicServicesKit';
  3. import { hilog } from '@kit.PerformanceAnalysisKit';
  4. 

  5. const TAG = 'SafetyDetectJsTest';
  6. 

  7. // 请求风控因子数据，并处理结果
  8. const request: safetyDetect.RiskFactorRequest = {
  9.  nonce: 'a1b2c3d4e5f6g7hfsdfxvsdae8', // 16-66字节的防重放随机数
  10.  queries: [
  11.      { factor: safetyDetect.RiskFactorType.HDC_DEBUG_STATE },
  12.      { factor: safetyDetect.RiskFactorType.IS_DEVELOPER_MODE },
  13.      { factor: safetyDetect.RiskFactorType.ODID_RESET_CNT }
  14.  ]
  15. };
  16. try {
  17.  hilog.info(0x0000, TAG, 'QueryRiskFactors begin.');
  18.  const response: safetyDetect.RiskFactorResponse = await safetyDetect.queryRiskFactors(request);
  19.  hilog.info(0x0000, TAG, 'Succeeded in QueryRiskFactors: %{public}s', response.result);
  20. } catch (err) {
  21.  let e: BusinessError = err as BusinessError;
  22.  hilog.error(0x0000, TAG, 'QueryRiskFactors failed: %{public}d %{public}s', e.code, e.message);
  23. }
DeviceVerify（应用设备状态检测）
RiskControlEngine（星盾机密风控引擎）
相关推荐
文档SecurityAudit（安全审计）
文档SecurityAudit
文档deviceDetection (设备硬件一致性检测)
文档BusinessRiskIntelligentDetection（业务风险检测）
文档DeviceVerify（应用设备状态检测）
文档系统完整性检测
文档本地系统完整性检测
文档updateManager（更新功能）
文档RiskControlEngine（星盾机密风控引擎）
文档系统完整性增强检测
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明
在 API参考 中进行搜索
请输入您想要搜索的关键词