# 获取SDK包与Demo 请先参照[开通服务页](https://www.volcengine.com/docs/86081/1660346)流程获得身份认证服务授权，再下载SDK包进行使用。 ### SDK --- ### Demo ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_23ce071eb622d9f8990478d3b0a98467.png =297x) *demo harmony test 体验过期时间：2026\-01\-24 （如果遇到过期请联系官网客服进行更新）* --- ### Demo工程源码若无火山引擎销售人员与您对接，请[点击此处](https://www.volcengine.com/contact/product?t=%E4%BA%BA%E5%83%8F%E4%BA%BA%E4%BD%93)申请试用,咨询问题请注明为身份认证。 # **在工程中导入SDK** ## 1. 将BytedCertSdk\-release.har 引入您的工程中 1. 拷贝BytedCertSdk\-release.har 到您工程的libs目录下 2. 配置oh\-package.json5, 在oh\-package.json5文件的dependencies中加入"bytedcertsdk"引用 ```Plain { "name": "your entry", "version": "******", "description": "******", "main": "******", "author": "******", "license": "******", "dependencies": { ....... "bytedcertsdk": "file:../libs/BytedCertSDK.har" ....... } } ``` ## 2.在您使用sdk的Ability中添加以下权限 ```Plain "requestPermissions": [ { "name": "ohos.permission.CAMERA", "usedScene": {"abilities": ['Your Ability']}, "reason": '$string:reason' }, { "name": "ohos.permission.WRITE_MEDIA", "usedScene": {"abilities": ['Your Ability']}, "reason": '$string:reason' }, { "name": "ohos.permission.READ_MEDIA", "usedScene": {"abilities": ['Your Ability']}, "reason": '$string:reason' }, { "name": "ohos.permission.INTERNET", "usedScene": {"abilities": ['Your Ability']}, "reason": '$string:reason' }, ] ``` ## 3. 设置Ability上下文在你的UIAbility中，设置Context，并在APPStorage中生成一个WindowStage ```SQL onWindowStageCreate(windowStage: window.WindowStage): void { .... BytedGlobalContext.getContext().setValue(ABILITY_CONTEXT,this.context) AppStorage.setOrCreate(WINDOW_STAGE,windowStage) .... } ``` ## 4. **其他配置** 本 Harmony SDK 基于 OpenHarmony SDK API Version 12 构建，推荐使用API 12以上版本开发。 ***如果您有平板适配需求，请在您的APP中先引导平板用户在系统”设置\-》显示和亮度\-》强制横屏“中把”强制横屏“开关关闭，否则将影响认证页正常运行。* ** # 调用流程 1. 鉴权参数设置，启动风控数据上报。 `initWithAccessKeyAndSecret()` 2. 等待风控数据上报完成 (initWithAccessKeyAndSecret 接口得到CommonRequestCallback回调后可以先进行后续身份认证逻辑，得到StringResultCallback回调代表风控数据验证成功) 3. 获取token：通过SDK的接口获取 bytedToken `startBytedToken()`，或者业务自行通过服务获取。 4. 拉起认证页： `startFaceCert//启动活体+身份认证` # 接口说明 ## 1.入口类BytedFaceLiveManager ### 1.1 获取BytedFaceLiveManager单例 BytedFaceLiveManager为ArkTS单例对象 ```Java /** * @return BytedFaceLiveManager对象 */ BytedFaceLiveManager.getManager(); ``` ### 1.2 设置鉴权参数与风控校验使用BytedCertConfig配置初始化参数 ```SQL /** * @param context: 上下文 * @param BytedCertConfig：鉴权参数信息 * @param securityTokenCallback: 接口回调，返回值为dev_token(设备稳定标识)， * 用于特殊需求自行组装端上请求，常规接入只需关注返回是否为空，返回代表风控校验完成，返回为空代表风控校验失败。 * @param initCallback: 接口回调，从服务器获取鉴权相关配置后即返回,返回结构response中 * 由于风控校验为耗时操作，不同设备上耗时表现不同。一般场景中此接口返回即可继续进行后续流程， * 通常情况下，最后的认证请求前都能完成风控校验，获得securityTokenCallback返回。 * 如有极少数特殊情况，后续操作过快导致风控校验未能完成，在认证最终步骤会体现为端上风险未知造成认证失败，引导用户重新完成认证即可。 * @return void * 默认使用正常采集模式进行风控数据采集，如需修改采集模版可以使用下面的方法设置securityMode参数实现。 */ BytedFaceLiveManager.getManager().initWithBytedConfig(BytedCertConfig.createConfig('your AK','your SK',your context),{ onResultFinish: (result: string): void => { // check dev_token } },{ onRequestFinish: (response: BDResponse): void => { if(response.success){ //do something when success }else{ //do something when success } } }) ``` 或者采用传统方式 ```SQL /** * @param context: 上下文 * @param stsToken: 鉴权配置使用临时密钥需要传入ststoken, 使用长期密钥时传null，强烈推荐使用临时密钥的方式，安全性更强 * @param accessKey: 密钥ak * @param secretAccessKey: 密钥sk * @param securityMode: 风控数据采集模版/可选字段开关。MODE_DEFAULT:正常模式,MODE_MINIMIZE:基础模式。基础模版不采集可选字段,风控识别能力低,建议使用DEFAULT模式。 * @param securityTokenCallback: 接口回调，返回值为dev_token(设备稳定标识)， * 用于特殊需求自行组装端上请求，常规接入只需关注返回是否为空，返回代表风控校验完成，返回为空代表风控校验失败。 * @param initCallback: 接口回调，从服务器获取鉴权相关配置后即返回 * 由于风控校验为耗时操作，不同设备上耗时表现不同。一般场景中此接口返回即可继续进行后续流程， * 通常情况下，最后的认证请求前都能完成风控校验，获得securityTokenCallback返回。 * 如有极少数特殊情况，后续操作过快导致风控校验未能完成，在认证最终步骤会体现为端上风险未知造成认证失败，引导用户重新完成认证即可。 * @return void */ //风控模式：MODE_NORMAL为普通模式（推荐模式）/MODE_MINIUM 为最小化模式，风控安全等级较低，不推荐 BytedFaceLiveManager.getManager().initWithAccessKeyAndSecret(your context,'your ststoken','your AK','your SK',BytedSecurityMode.MODE_NORMAL,{ onResultFinish: (result: string): void => { // check dev_token } },{ onRequestFinish: (response: BDResponse): void => { if(response.success){ //do something when success }else{ //do something when success } } }) ``` ### 1.3 获取token 如果从服务端获取token，则此步骤可以忽略不做 ```SQL //params //refSource 有源/无源开关 1有源 0无源 2单活体比对 //params 活体配置参数，可以传空，传空代表使用服务端下发配置，具体取值见3.params 活体配置参数介绍 //callback 执行完成回调 BytedFaceLiveManager.getManager().startBytedToken(refSource: number, params: Map, callback:{ onBytedTokenFinish: (errorCode: number, errorMsg: string, bytedToken: string, jsonData: string) => void): void { } } ``` 回调数据返回值说明见[身份认证增强版sdk返回内容说明](https://bytedance.larkoffice.com/docx/B1lSdCTx1okBgkxbbONcE04snRq) ### 1.4 配置视频录制参数有需要对于视频上传桶进行自定义，或者需要在端上获取视频信息的可以通过此接口进行配置。 ```java /** * @param tosInfo: tos配置，可空，当传空时，默认使用服务端端配置。 * @param callback: 视频上传callback, 注意：返回非主线程 * @return void */ public configRecordeAndUploadParams(tosInfo : BytedCertTosInfo | null , uploadVideoCallback : UploadVideoCallback) ``` Example: ```java let bytedTosInfo : BytedCertTosInfo = BytedCertTosInfo.createTosInfo("ak", "sk", "sts_token", "bucket", "tos-cn-beijing.volces.com", "cjq-test.tos-cn-beijing.volces.com"); BytedFaceLiveManager.getManager().configRecordeAndUploadParams(bytedTosInfo, { onUploadFinsh: (bytedToken: string, errorCode: number, errorMsg: string, filePath: string | undefined): void => { if(filePath){ //use the file fs.rmdir(filePath) }else{ //do something when failed } } }); ``` ### 1.5 ocr识别接口 ```java /** * @param context: Android上下文 * @param ocrCallback: ocr识别结果回调，详细参数见2.4 SDKCallBack.OcrCallback介绍 * @return void */ public void doOCRH5(ocrCallback: OCRCallback) ``` Example: ```Plain BytedFaceLiveManager.getInstance().doOCRH5(mContext, new SDKCallBack.OcrCallback(){ @Override public void onOcrFinish(final int errorCode, final String errorMsg, final String identityCode, final String identityName, String cardImgFront, String cardImgBack) { runOnUiThread(new Runnable() { @Override public void run() { if (errorCode == 0) { Toast.makeText(mContext, "ocr识别成功, 姓名：" + identityName, Toast.LENGTH_SHORT).show(); } else { Toast.makeText(mContext, "ocr识别失败, " + errorMsg, Toast.LENGTH_SHORT).show(); } } }); } }); ``` ### 1.6 拉起人脸页拉起人脸页进行有源/无源认证，如果是在客户端获取token的话，建议在获取token成功的回调中进行此步操作 ```SQL //params //abilityContext 当前AbilityContext //refSource 有源/无源开关 true有源 false无源 //faceCertConfig 认证参数 //bytedToken 唯一ID //clientConfig : 从startBytedToken中获取，也可使用服务端中的bytedToken中返回的 //callback 执行完成回调 BytedFaceLiveManager.getManager().startFaceCert(abilityContext,new FaceCertConfig(true,true,true),bytedToken,clientParams, { onCertFinish: (errorCode: number, errorMsg: string, jsonData: string, jsonDataObj: object | undefined): void => { if(errorCode == 0 || errorCode == 10000){ this.showResult("认证成功") }else{ this.showResult("认证失败 (" + errorCode + ")" + errorMsg) } }) ``` 回调数据返回值说明见[身份认证增强版sdk返回内容说明](https://bytedance.larkoffice.com/docx/B1lSdCTx1okBgkxbbONcE04snRq) FaceCertConfig 认证参数类: ```SQL export class FaceCertConfig{ //是否进行认证，如果只进行OCR或者只进行端活体可以为false，其他情况均为true needVerify : boolean = true //认证方式有源:1/无源:0/单活体:2 refSource : number //语音播报开关 textSpeech : boolean = false } ``` ### 1.7 启动完整认证流程，先做ocr再做有源比对 ```java /** * 认证相关配置 * @param needVerify: 是否需要进行后续服务的有源/无源比对，默认为true。 * @param refSource： 0为无源比对，1为有源比对，2为只做活体不比对 * @param textSpeech: 文本播报功能默认值为false，表示不进行语音播报。 */ export class FaceCertConfig{ needVerify : boolean = true refSource : number = -1 textSpeech : boolean = false } /** * @param context: Android上下文 * @param faceCertConfig: 认证相关配置 * @param params: 活体配置参数，具体取值见3.params 活体配置参数介绍介绍 * @param callback: 返回token结果的callback，详细参数见2.2 BytedSDKCallBack.CertResultCallback介绍 * @return void */ beginAuthorizationWithParams(params : HashMap,faceCertConfig : FaceCertConfig,callback: CertResultCallback): void ``` Example: ```java let params = new HashMap() params.set("risk_motion_list", "{"free":["0","1","2","3"],"low":["0","1","2","3"], "medium":["0","1","2","3"],"high":["0","1","2","3"]}") params.set("risk_motion_count", "{"free":2,"low":2,"medium":3,"high":4}"); params.set("liveness_timeout", 10); params.set("risk_fixed_motion_list", "{"free":["0","1","2","3"],"low":["0","1","2","3"], "medium":["0","1","2","3"],"high":["0","1","2","3"]}"); params.set("max_liveness_trial", mMaxLivenessTrial); BytedFaceLiveManager.getManager().beginAuthorizationWithParams(params,new FaceCertConfig(true,your_self_ref_source,your_isEnableSpeak),yourResultCallback) ``` 例子代码中，params参数作用同1.3获取token接口中params参数作用，为端上配置活体参数用，详见“3.params 活体配置参数介绍”中的详述。 ## 2. callback ### 2.1 BytedSDKCallBack.UploadVideoCallback ```java /** * onUploadFinsh参数 * @param bytedToken: 视频对应的bytedToken * @param errorCode: 错误码，成功的话为0 * @param errorMsg: 错误信息成功的话为"" * @param filePath: 录制的视频路径失败的话为undefined或"" */ export interface UploadVideoCallback{ onUploadFinsh:(bytedToken: string, errorCode: number, errorMsg: string, filePath: string | undefined) => void } ``` ### ### 2.2 BytedSDKCallBack.CertResultCallback 返回数据jsonData的数据格式参考[身份认证sdk返回内容说明](https://bytedance.feishu.cn/docx/B1lSdCTx1okBgkxbbONcE04snRq) ```Java export interface CertResultCallback { //errorCode，错误码 //errorMsg，错误信息 //jsonData，返回数据, 详细数据格式参考人脸核身服务端api的返回字段中的"resp_data" //jsonDataObj，返回数据对象 onCertFinish:(errorCode: number, errorMsg: string, jsonData: string, jsonDataObj: object | undefined) => void } ``` ### Example: 由于此callback为认证结果接口所使用，使用频率最高，这里为方便理解，提供一个callback的应用示例作为开发者开发指导。仅供开发者参考，推荐开发者根据自己业务场景改写。 ```Plain Text let resultCallback : CertResultCallback= { onCertFinish: async (errorCode: number, errorMsg: string, jsonData: string, jsonDataObj: object | undefined ): Promise => { if(jsonDataObj != undefined) { let doCertVerifyResponse = jsonDataObj as DoCertVerifyResponse if (doCertVerifyResponse != null) { // 获取详细信息的方法：建议在调试阶段打印jsonData内容以了解所有可用的错误信息字段 // 1. errorCode 和 errorMsg 提供了基础的错误描述 // 2. jsonData 字段是完整的JSON格式响应数据，可以从中提取更多详细信息 // 3. jsonDataObj 是jsonData解析后的对象形式，可以直接访问其中的字段 // 4. RequestID 可以通过该ID查询日志，通常保存在服务端 const requestId = doCertVerifyResponse.request_id; // 以下获取的图片为Base64的字符串，可以存储到数据库或者本地进行后续处理 let image_best = doCertVerifyResponse.data.images.image_best let image_env = doCertVerifyResponse.data.images.image_env // errorCode == 0 表示认证成功非0即失败 if(errorCode == 0){ // TODO: 添加成功的处理逻辑 // 1. 更新UI显示认证成功结果 // 2. 可以进行后续业务流程，如跳转页面等操 this.showResult("认证成功") }else{ // 认证失败处理 // 1. 更新UI显示详细错误信息，包括错误码和错误描述 // 2. 建议记录错误日志以便后续分析 // 3. 根据不同的错误码可以进行特殊处理，例如： // - 其他系统错误：建议用户重试或联系客服 // 失败：errorCode = -5021, errorMsg = "验证未通过，请确认为本人操作并确保设备安全" this.showResult("认证失败 (" + errorCode + ")" + errorMsg) // 可以获取子错误码发送到服务器,子错误码含义： https://www.volcengine.com/docs/86081/1660363 //以下2个字段为原始错误信息，可以反馈是何种原因导致的错误，错误信息为一段英文描述 const directErrorCode = doCertVerifyResponse.data.algorithm_base_resp.status_code; const directErrorMsg = doCertVerifyResponse.data.algorithm_base_resp.status_message; // TODO: 根据实际需求对错误码匹配自定义的错误添加更详细的错误处理逻辑，此处的directErrorCode为字错误码 } } }else{ //用户主动取消操作时 JSONDataObj为undefined，JSONData为空 if(errorCode == -1006){ //TODO: 添加用户主动取消认证的逻辑 this.showResult("用户主动取消") } } } } ``` ### 2.3 BytedSDKCallBack.BytedTokenCallback ```java /** * onResultFinish参数 * @param errorCode 错误码 * @param errorMsg 错误信息 * @param bytedToken，返回的bytenToken值 * @paramd client_config 客户端配置，原样传给startFaceCert即可 * @paramd jsonData 服务端返回原始jsondata透传 */ export interface BytedTokenCallback { onBytedTokenFinish:(errorCode: number, errorMsg: string, bytedToken: string, client_config : string, jsonData: string) => void } ``` ### 2.4 BytedSDKCallBack.OCRCallback ```java /** * onResultFinish参数 * @param errorCode 错误码 * @param errorMsg 错误信息 * @param identityCode 身份证id * @paramd indentityName 姓名 * @param cardImgFront 身份证正面图片 * @paramd cardImgBack 身份证背面图片 */ export interface OCRCallback { onOCRFinish:(errorCode: number, errorMsg: string, indentityCode: string, indentityName: string, cardImgFront: string, cardImgBack: string) => void } ``` ## 3. params 活体配置参数介绍此字段为端上配置活体参数入口，params传空代表使用服务端下发配置推荐活体参数配置在服务端下发，服务端下发配置可在控制台动态调整，且支持创建子应用实现配置隔离，具体控制台配置方式可以咨询客服。 |**key** |**说明** |**默认值** | |---|---|---| |idcard_name |身份证名称, 有源比对需要传 | | |idcard_no |身份证id，有源比对为需要传 | | |risk_liveness_type |风险等级对应的活体类型，取值有|"risk_liveness_type": |\ | |“motion”(动作活体),| |\ | |“reflection”(炫彩活体)。| |\ | |格式为json string ，各风险对应的活体类型的取值类型为String。 | | |risk_motion_list |风险等级对应的下发动作列表，取值有| *"risk_motion_list":{* *"free":["0","1","2","3"],//无风险，全部下发* *"low":["0","1","2","3"], //低风险, 全部下发* *"medium":["0","1","2","3"],//中风险 , 全部下发* *"high":["0","1","2","3"]//高风险, 全部下发* *}* |\ | |“0”(*眨眼*)| |\ | |"1"(*张嘴*)| |\ | |"2"(*点头*)| |\ | |"3"(*摇头*)| |\ | |格式为json string，各风险对应的动作的取值类型为String数组。 | | |risk_motion_count |风险等级对应的下发动作数量，*可选范围：[1, 4]* | *"risk_motion_count":{* \*\* "free":2, //无风险，下发两个动作\* \*\* "low":2, //低风险, 下发两个动作\* \*\* "medium":3, //中风险 , 下发三个动作\* \*\* "high":4,//高风险, 下发两四动作\* \*\* }\* |\ | |格式为json string，各风险对应的动作的取值类型为Int。| |\ | |取值需要结合risk_motion_list配置的动作列表，风险的对应的下发动作数量不能大于对应的下发动作列表数量。 | | |risk_fixed_motion_list |风险等级对应的固定下发动作列表，取值有|默认不传 |\ | |“0”(*眨眼*)| |\ | |"1"(*张嘴*)| |\ | |"2"(*点头*)| |\ | |"3"(*摇头*)| |\ | |格式为json string，各风险对应的动作的取值类型为String数组。 | | |liveness_timeout |端上活体超时时长，可选范围： [5, 60] |10 | |max_liveness_trial |端上动作活体最大尝试次数, 可选范围：[1, 100] |10 | # 错误码：详见[SDK端上错误码说明](https://www.volcengine.com/docs/86081/2124467?lang=zh)

图像生成大模型