# 获取SDK包与Demo 请先参照[开通服务页](https://www.volcengine.com/docs/86081/1660346)流程获得身份认证服务授权，再下载SDK包进行使用。 ### SDK ***在主应用中同时集成了火山APM相关能力用上述包集成会报冲突的，可以尝试用下面的包尝试集成，如果仍然报错请尝试拉起oncall，或者联系火山技术支持人员。* ** --- ### Demo --- ### Demo工程源码若无火山引擎销售人员与您对接，请[点击此处](https://www.volcengine.com/contact/product?t=%E4%BA%BA%E5%83%8F%E4%BA%BA%E4%BD%93)申请试用,咨询问题请注明为身份认证。 *注：Demo工程中自带sdk可能并非最新发布，请自行更换成最近版本* # **在工程中导入SDK** ## 1. 将BytedCertSdk\-release.aar 引入您的工程中 1. 拷贝BytedCertSdk\-release.aar 到您工程的libs目录下 2. 配置gradle, build.gradle中加入flatDir，并在dependencies中加入implementation(name:'BytedCertSdk\-release', ext:'aar') ```Plain repositories { flatDir{ dirs 'libs' } } dependencies { //本地依赖 implementation(name:'BytedCertSdk-release', ext:'aar') //远程依赖 implementation 'androidx.constraintlayout:constraintlayout:2.1.4' implementation ’androidx.window:window-java:1.1.0-alpha01‘ implementation ‘org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.3.10’ implementation 'com.android.support:appcompat-v7:28.0.0' implementation 'com.squareup.okhttp3:okhttp:3.4.1' implementation 'com.amazonaws:aws-android-sdk-s3:2.12.7' implementation 'org.bouncycastle:bcprov-jdk15to18:1.70' implementation 'org.bouncycastle:bcpkix-jdk15to18:1.70' } ``` ## 2. AndroidManifest.xml添加以下权限权 ```Plain

``` ## 3. 如果开启了混淆（minifyEnabled true），需要在混淆文件中添加以下配置 ```Plain -keepattributes Signature -keepattributes Exceptions,InnerClasses -keep class ms.bz.bd.**{ *; } -keep class com.bytedance.** {*;} -keep class com.volcengine.mobsecBiz.**{ *; } -keep class kotlinx.coroutines.** {*;} # security sdk for com.volcengine.bizssdk:ml:7.0.1.mlBusiness -keepattributes Signature -keepattributes Exceptions,InnerClasses -keep class ms.bz.bd.**{ *; } -keep class com.volcengine.mobsecBiz.**{ *; } -keepnames class com.bytedance.applog.** -keep class com.bytedance.crash.** #java Encryption and decryption sdk bouncycastle -keep class org.bouncycastle.** #amazonaws s3 -keepnames class com.amazonaws.** -keepnames class com.amazon.** # Enums are not obfuscated correctly in combination with Gson -keepclassmembers enum * { *; } # Request handlers defined in request.handlers -keep class com.amazonaws.services.**.*Handler # The following are referenced but aren't required to run -dontwarn com.fasterxml.jackson.** -dontwarn org.apache.http.** # The SDK has several references of Apache HTTP client -dontwarn com.amazonaws.http.** -dontwarn com.amazonaws.metrics.** ``` ## 4. **其他配置** 本 Android SDK 基于 Java8 构建，支持的 minSDK 版本为 API 23（*由于历史原因，有些版本发包minSDK版本还会是API 21，但回归测试已经不会覆盖到API 23以下版本系统，并不保证API 23以下平台的效果与可用性*）。对于 minSDK 版本低于 API 26（不包括26）的 Android 应用，需额外进行如下设置才能正常运行 ### 相关依赖 * Gradle 6.1.1 或更高版本 * Android Gradle 插件 4.0.0 或更高版本 * 在您的安卓应用模块（通常在 app 目录下）的 build.gradle 文件中，添加如下代码 ```java android { compileOptions { sourceCompatibility JavaVersion.VERSION_1_8 targetCompatibility JavaVersion.VERSION_1_8 } } ``` # 调用流程 1. 鉴权参数设置，启动风控数据上报。 `setSignAccessKeySecretAccessKey()` 2. 进行身份认证 (setSignAccessKeySecretAccessKey接口回调后才能进行身份认证逻辑) 1. 全流程启动：OCR+活体检测+身份认证 `beginAuthorizationWithParams()` 2. 启动活体：通过SDK的接口获取 bytedToken `startBytedToken()`，或者业务自行通过服务获取。 `startFaceCert//启动活体+身份认证` ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_d0456c8fe915789da712100a11c06dee.jpg =1834x) # 接口说明 ## 1.入口类BytedFaceLiveManager ### 1.1 获取BytedFaceLiveManager单例 BytedFaceLiveManager为kotlin单例对象 ```Java /** * @return BytedFaceLiveManager对象 */ //Java类中使用 BytedFaceLiveManager.INSTANCE; ``` ### 1.2 设置鉴权参数与风控校验 ```java /** * @param context: Android上下文 * @param stsToken: 鉴权配置使用临时密钥需要传入ststoken, 使用长期密钥时传null，强烈推荐使用临时密钥的方式，安全性更强 * @param accessKey: 密钥ak * @param secretAccessKey: 密钥sk * @param callback: 接口回调，返回值为dev_token(设备稳定标识) * @return void * 默认使用正常采集模式进行风控数据采集，如需修改采集模版可以使用下面的方法设置securityMode参数实现。 */ public void setSignAccessKeySecretAccessKey(Context appContext, String stsToken, String accessKey, String secretAccessKey, SDKCallBack.StringResultCallback callback) ``` ```java /** * @param context: Android上下文 * @param stsToken: 鉴权配置使用临时密钥需要传入ststoken, 使用长期密钥时传null，强烈推荐使用临时密钥的方式，安全性更强 * @param accessKey: 密钥ak * @param secretAccessKey: 密钥sk * @param securityMode: 风控数据采集模版/可选字段开关。取值“0”-MODE_DEFAULT:正常模式,取值“1”-MODE_MINIMIZE:基础模式。基础模版不采集可选字段（不会采集BSSID、IMEI、MEID、Mac地址、MSIN/IMSI）,风控识别能力低,建议使用DEFAULT模式。 * @param callback: 接口回调，返回值为dev_token(设备稳定标识) * @return void */ public void setSignAccessKeySecretAccessKey(Context appContext, String stsToken, String accessKey, String secretAccessKey,int securityMode SDKCallBack.StringResultCallback callback) ``` ### 1.3 获取设备稳定标识 > 请求服务端接口时需要带上该参数。 ```java /** * @return SecurityInfo 风控配置信息 */ public SecurityInfo getSecurityInfo() ``` Example: ```java BytedFaceLiveManager.getInstance().getSecurityInfo().getSecurityToken(); ``` ### 1.4 配置视频录制参数有需要对于视频上传桶进行自定义，或者需要在端上获取视频信息的可以通过此接口进行配置。 ```java /** * @param tosInfo: tos配置，可空，当传空时，默认使用服务端端配置。 * @param callback: 视频上传callback, 注意：返回非主线程 * @return void */ public void configRecordeAndUploadParams(BytedCertTosInfo tosInfo, SDKCallBack.UploadVideoCallback callback) ``` Example: ```java BytedCertTosInfo bytedTosInfo = BytedCertTosInfo.createTosInfo("ak", "sk", "sts_token", "bucket", "tos-cn-beijing.volces.com", "cjq-test.tos-cn-beijing.volces.com"); BytedFaceLiveManager.getInstance().configRecordeAndUploadParams(bytedTosInfo, new SDKCallBack.UploadVideoCallback() { @Override public void onUploadFinsh(String bytedToken, final int errorCode, final String errorMsg, final String filePath) { bytedCertManager.executeInMainThread(new Runnable() { @Override public void run() { mUploadLog.setVisibility(View.VISIBLE); if (errorCode == 0) { mUploadLog.setText("上传视频成功：" + filePath); FileUtils.deleteFileByPath(filePath); }else { mUploadLog.setText(String.format("上传视频失败(%d): %s", errorCode, errorMsg)); } } }); } }); ``` ### 1.5 ocr识别接口 ```java /** * @param context: Android上下文 * @param ocrCallback: ocr识别结果回调，详细参数见2.2 SDKCallBack.OcrCallback介绍 * @return void */ public void doOCRH5(Context context, SDKCallBack.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接口 ```java /** * @param refSource: true为有源比对，false为无源比对 * @param params: 活体配置参数，可以传空，传空代表使用服务端下发配置，具体取值见3.params 活体配置参数介绍 * @param callback: 返回token结果的callback，详细参数见2.4 SDKCallBack.BytedTokenCallback介绍 * @return void */ public void startBytedToken(boolean refSource, Map params, SDKCallBack.BytedTokenCallback callback) ``` Example: ```java //无源比对 HashMap params = new HashMap<>(); params.put("risk_motion_list", "{"free":["0","1","2","3"],"low":["0","1","2","3"], "medium":["0","1","2","3"],"high":["0","1","2","3"]}"); params.put("risk_motion_count", "{"free":2,"low":2,"medium":3,"high":4}"); params.put("liveness_timeout", 10); params.put("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.put("max_liveness_trial", mMaxLivenessTrial); BytedFaceLiveManager.getInstance().startBytedToken(false, params, new SDKCallBack.BytedTokenCallback() { @Override public void onBytedTokenFinish(int errorCode, String errorMsg, String bytedToken, String clientConfig, JSONObject jsonData) { if (errorCode == 0 && !bytedToken.isEmpty() && !clientConfig.isEmpty()) { mBytedToken = bytedToken; mClientConfig = clientConfig } } }); ``` ### 1.7 启动活体 ```java /** * 认证相关配置 * 这里由于2.4.0版本以后新增了“单活体比对”调用方式，故增加新的数据结构参数，建议都用此数据结构参数作为输入 * 原来的‘CertConfig’仍然兼容，但会逐渐弃用 * @param needVerify: 是否需要进行后续服务的有源/无源比对，默认为true。 * @param refSource： 0为无源比对，1为有源比对，2为只做活体不比对 * @param textSpeech: 文本播报功能默认值为false，表示不进行语音播报。 */ data class CertConfigV2( val needVerify: Boolean = true, val refSource: Int = -1, val textSpeech: Boolean = false ) /** * @param context: Android上下文 * @param certConfig: 认证相关配置 * @param bytedToken: 通过1.5的startBytedToken接口获取，或者通过服务端中TokenPro中获取。一般使用后者方式获取。 * @param clientConfig: 从startBytedToken获取，同时也可以使用服务端中TokenPro中返回的clientConfig * @param callback: 返回token结果的callback，详细参数见2.3 SDKCallBack.ResultCallback介绍 * @return void */ public void startFaceCert(Context context, CertConfigV2 certConfig, String byteToken, String clientConfig, SDKCallBack.ResultCallback callback) ``` Example: ```java //有源比对 BytedFaceLiveManager.getInstance().startFaceCert(NativeFLN.this, new CertConfigV2(true, your_refSource, false), bytedToken, clientConfig, new SDKCallBack.ResultCallback(){ @Override public void onResultFinish(int errorCode, String errorMsg, JSONObject jsonData) { if (loadingDialog != null) { loadingDialog.dismiss(); } if (errorCode == 0) { Toast.makeText(mContext, "活体成功", Toast.LENGTH_SHORT).show(); } else { Toast.makeText(mContext, "活体失败：" + errorMsg, Toast.LENGTH_SHORT).show(); } } }); ``` ### 1.8 启动完整认证流程，先做ocr再做有源比对 ```java /** * 认证相关配置 * 这里由于2.4.0版本以后新增了“单活体比对”调用方式，故增加新的数据结构参数，建议都用此数据结构参数作为输入 * 原来的‘CertConfig’仍然兼容，但会逐渐弃用 * @param needVerify: 是否需要进行后续服务的有源/无源比对，默认为true。 * @param refSource： 0为无源比对，1为有源比对，2为只做活体不比对 * @param textSpeech: 文本播报功能默认值为false，表示不进行语音播报。 */ data class CertConfigV2( val needVerify: Boolean = true, val refSource: Int = -1, val textSpeech: Boolean = false ) /** * @param context: Android上下文 * @param certConfig: 认证相关配置 * @param params: 活体配置参数，具体取值见3.params 活体配置参数介绍介绍 * @param callback: 返回token结果的callback，详细参数见2.3 SDKCallBack.ResultCallback介绍 * @return void */ public void beginAuthorizationWithParams(Context context, CertConfigV2 certConfig, Map params, SDKCallBack.ResultCallback callback) ``` Example: ```java HashMap params = new HashMap<>(); params.put("risk_motion_list", "{"free":["0","1","2","3"],"low":["0","1","2","3"], "medium":["0","1","2","3"],"high":["0","1","2","3"]}"); params.put("risk_motion_count", "{"free":2,"low":2,"medium":3,"high":4}"); params.put("liveness_timeout", 10); params.put("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.put("max_liveness_trial", mMaxLivenessTrial); BytedFaceLiveManager.getInstance().beginAuthorizationWithParams(WelcomeActivity.this, true, params, new SDKCallBack.ResultCallback(){ @Override public void onResultFinish(int errorCode, String errorMsg, JSONObject jsonData) { if (errorCode == 0) { Toast.makeText(mContext, "活体成功", Toast.LENGTH_SHORT).show(); } else { Toast.makeText(mContext, "活体成功失败：" + errorMsg, Toast.LENGTH_SHORT).show(); } } }); ``` 例子代码中，params参数作用同1.5获取token接口中params参数作用，为端上配置活体参数用，详见“3.params 活体配置参数介绍”中的详述。 ## 2. callback ### 2.1 SDKCallBack.UploadVideoCallback ```java /** * onUploadFinsh参数 * @param bytedToken: 视频对应的bytedToken * @param errorCode: 错误码，成功的话为0 * @param errorMsg: 错误信息成功的话为"" * @param filePath: 录制的视频路径失败的话为"" */ interface UploadVideoCallback { void onUploadFinsh(String bytedToken, int errorCode, String errorMsg, String filePath); } ``` ### 2.2 SDKCallBack.OcrCallback ```java /** * onOcrFinish参数 * @param errorCode 错误码 * @param errorMsg 错误信息 * @param identityCode 身份证id * @paramd entityName 姓名 * @param cardImgFront 身份证正面图片 * @paramd cardImgBack 身份证背面图片 */ interface OcrCallback { void onOcrFinish(int errorCode, String errorMsg, String identityCode, String identityName, String cardImgFront, String cardImgBack); } ``` ### 2.3 SDKCallBack.ResultCallback 返回数据jsonData的数据格式参考[身份认证sdk返回内容说明](https://bytedance.feishu.cn/docx/B1lSdCTx1okBgkxbbONcE04snRq) ```Java interface ResultCallback { //errorCode，错误码 //errorMsg，错误信息 //jsonData，返回数据, 详细数据格式参考人脸核身服务端api的返回字段中的"resp_data" void onResultFinish(int errorCode, String errorMsg, JSONObject jsonData); } ``` Example: 由于此callback为认证结果接口所使用，使用频率最高，这里为方便理解，提供一个callback的应用示例作为开发者开发指导。仅供开发者参考，推荐开发者根据自己业务场景改写。 ```Plain Text final SDKCallBack.ResultCallback callback = new SDKCallBack.ResultCallback() { @Override public void onResultFinish(int errorCode, String errorMsg, JSONObject resp_data) { if(errorCode == 0){ //这里可以添加认证成功的端上逻辑 //这里以解析返回体中的人脸图和环境图为例 if (!resp_data.isNull("images")) { try { JSONObject images = resp_data.getJSONObject("images"); String image_best = images.optString("image_best"); //返回结果中的人脸图 String image_env = images.optString("image_env"); //返回结果中的环境图 //人脸图解base64 byte[] decodedString = Base64.decode(image_best, Base64.NO_WRAP); Bitmap decodedByte = BitmapFactory.decodeByteArray(decodedString, 0, decodedString.length); //环境图解base64 byte[] decodedStringEnv = Base64.decode(image_env, Base64.NO_WRAP); Bitmap decodedByteEnv = BitmapFactory.decodeByteArray(decodedStringEnv, 0, decodedStringEnv.length); } catch (JSONException e) { e.printStackTrace(); } } }else{ //这里处理认证失败与认证链路中其他失败逻辑 try { if(resp_data != null && resp_data.has("algorithm_base_resp")) { //这里可以先尝试解析“algorithm_base_resp”中的子错误码查看错误原因 JSONObject algorithm_base_resp = resp_data.getJSONObject("algorithm_base_resp"); int status_code = algorithm_base_resp.getInt("status_code"); String status_message = algorithm_base_resp.optString("status_message",""); }else { //也会出现认证链路没有触达服务端就出错的情况，如网络异常等，在这里兜底处理 } } catch (JSONException e) { e.printStackTrace(); } } } }; ``` ### 2.4 SDKCallBack.BytedTokenCallback ```java /** * onResultFinish参数 * @param errorCode 错误码 * @param errorMsg 错误信息 * @param bytedToken，返回的bytenToken值 * @paramd client_config 客户端配置，原样传给startFaceCert即可 * @paramd jsonData 服务端返回原始jsondata透传 */ interface BytedTokenCallback { void onResultFinish(int errorCode, String errorMsg, String bytedToken, String client_config, JSONObject jsonData); } ``` ## 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 | |reflection_mode |炫彩校验模式，当risk_liveness_type命中reflection动作类型时生效，字段类型为int，取值有|0 |\ | |0（默认）| |\ | |1（严格） | | ## 4.活体认证信息回调说明 ### 4.1 facelive_info数据结构身份认证包含**活体检测**和**身份认证**两个步骤, 如**活体检测**成功, 在**启动活体/启动完整认证流程**接口的回调里会把活体认证相关的结果(最佳帧数据和一小段视频数据)回调到ResultCallback的resp_data(JsonObject)信息中, 具体字段结构如下： ```json data = { "facelive_info": { "info": 认证信息 } } "info": { "image": Base64编码数据, "video": Base64编码数据 } ``` ### 4.2 活体信息处理活体认证信息主要返回的信息为: 1. 认证过程中的最佳图片. 2. 认证过程中的最佳视频片段. #### 活体信息结果处理伪代码 ```kotlin fun handleResultData(context: Context, resp_data: JSONObject?) { GlobalScope.launch(Dispatchers.IO) { resp_data?.optJSONObject("facelive_info")?.let { faceLiveInfoJsonObject -> faceLiveInfoJsonObject.optJSONObject("info")?.let { infoJsonObject -> //处理视频数据 infoJsonObject.optString("video").takeIf { it.isNotEmpty() } ?.let { videoData -> val base64dDecodeData = Base64.decode(videoData, Base64.NO_WRAP) val targetFilePath = "${context.externalCacheDir?.absolutePath ?: context.filesDir.absolutePath}/test.mp4" writeContentToFile( base64dDecodeData, targetFilePath ) Log.d(TAG, "writeContentToFile video finish path $targetFilePath") } //处理图片数据 infoJsonObject.optString("image").takeIf { it.isNotEmpty() } ?.let { imageData -> val base64dDecodeData = Base64.decode(imageData, Base64.NO_WRAP) val targetFilePath = "${context.externalCacheDir?.absolutePath ?: context.filesDir.absolutePath}/test.jpg" writeContentToFile(base64dDecodeData, targetFilePath) Log.d(TAG, "writeContentToFile image finish path $targetFilePath") } } } } } ``` # 错误码：详见[SDK端上错误码说明](https://www.volcengine.com/docs/86081/2124467?lang=zh)

图像生成大模型