文档中心

Android版本

最近更新时间：2024.01.10 15:52:05

首次发布时间：2022.10.27 23:22:27

接入前体验

若无火山引擎销售人员与您对接，请点击此处申请试用,咨询问题请注明为身份认证。

Android端体验地址

获取SDK包与Demo

Android SDK

请先参照开通服务页流程获得身份认证服务授权，再下载SDK包进行使用。

BytedCertSdk-release_2.1.2.aar.zip

3.45MB

Demo

BytedCertSdk-Sample_2.1.2.zip

3.69MB

在工程中导入SDK

1.将BytedCertSdk-release.aar 引入您的工程中

a.拷贝BytedCertSdk-release.aar 到您工程的libs目录下

b.配置gradle, build.gradle中加入flatDir，并在dependencies中加入implementation(name:'BytedCertSdk-release', ext:'aar')

repositories {
    flatDir{
        dirs 'libs'
    }
}

dependencies {
    //本地依赖
    implementation(name:'BytedCertSdk-release', ext:'aar')
    //远程依赖
    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
    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'
}

2.AndroidManifest.xml添加以下权限权

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/> 
<uses-permission android:name="android.permission.CAMERA" />

3.如果开启了混淆（minifyEnabled true），需要在混淆文件中添加以下配置

-keep class com.bytedance.** {*;}
#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.**

# Android 6.0 release removes support for the Apache HTTP client
-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 21。对于 minSDK 版本低于 API 26（不包括26）的 Android 应用，需额外进行如下设置才能正常运行

1. 入口类BytedFaceLiveManager

1.1 获取BytedFaceLiveManager单例

/**
 *  @return  BytedFaceLiveManager单例对象
 */
public static BytedFaceLiveManager getInstance()

1.2 设置鉴权参数

/**
 *  @param  context: Android上下文
 *  @param  stsToken: 鉴权配置  使用临时密钥需要传入ststoken, 使用长期密钥时传null，强烈推荐使用临时密钥的方式，安全性更强
 *  @param  accessKey: 密钥ak
 *  @param  secretAccessKey: 密钥sk
 *  @return  void
 */
public void setSignAccessKeySecretAccessKey(Context appContext, String stsToken, String accessKey, String secretAccessKey)

1.3 配置视频录制参数

/**
 *  @param  tosInfo:  tos配置，可空，当传空时，默认使用服务端端配置。
 *  @param  callback: 视频上传callback, 注意：返回非主线程
 *  @return  void
 */
public void configRecordeAndUploadParams(BytedCertTosInfo tosInfo, SDKCallBack.UploadVideoCallback callback)

Example:

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.4 ocr识别接口

/**
 *  @param  context:     Android上下文
 *  @param  ocrCallback: ocr识别结果回调，详细参数见2.2 SDKCallBack.OcrCallback介绍
 *  @return  void
 */
public void doOCRH5(Context context, SDKCallBack.OcrCallback ocrCallback)

Example :

BytedFaceLiveManager.getInstance().doOCRH5(mContext, new SDKCallBack.OcrCallback(){
    @Override
    public void onOcrFinish(final int errorCode, final String errorMsg, final String identityCode, final String identityName) {
        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.5 获取token接口

/**
 *  @param  refSource: true为有源比对，false为无源比对
 *  @param  params:    活体配置参数，具体取值如下：
 *        idcard_name： 身份证名称, 有源比对为必传
 *        idcard_no： 身份证id，有源比对为必传
 *        motion_list：活体动作列表，以','隔开，例"0,1,2" //0:"眨眼",1:"张嘴",2:"点头",3:"摇头" 
 *        motion_count：需要的活体动作个数，从motion_list中选择motion_count个，需要小于等于 
 *        motion_list中的个数
 *        liveness_timeout: 端上活体超时时长，可选范围： [5, 60]，默认：10
 *        fixed_motion_list: 固定一定需要下发的动作列表, 取值同motion_list
 *        max_liveness_trial: 端上动作活体最大尝试次数, 可选范围：[1, 100]，默认：10
 *  @param  callback: 返回token结果的callback，详细参数见2.4 SDKCallBack.BytedTokenCallback介绍
 *  @return  void
 */
public void startBytedToken(boolean refSource, Map<String, String> params, SDKCallBack.BytedTokenCallback callback)

Example:

//无源比对
HashMap<String, String> params = new HashMap<>();
params.put("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"]}");
params.put("risk_motion_count", ""risk_motion_count":"free":2,"low":2,"medium":3,"high":4}");
params.put("liveness_timeout", 10);
params.put("risk_fixed_motion_list", ""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);
//如果为有源比对的话，refSource为true。
BytedFaceLiveManager.getInstance().startBytedToken(false, params, new SDKCallBack.BytedTokenCallback() {
    @Override
    public void onBytedTokenFinish(int errorCode, String errorMsg, String bytedToken, String clientConfig) {
        if (errorCode == 0 && !bytedToken.isEmpty() && !clientConfig.isEmpty()) {
            mBytedToken = bytedToken;
            mClientConfig = clientConfig
        }
    }
});

1.6 启动活体

/**
 * 认证相关配置
 * @param  refSource:  true为有源比对，false为无源比对
 * @param  textSpeech: 文本播报功能 默认值为false，表示不进行语音播报。
 */
class CertConfig( 
     boolean refSource,
     boolean textSpeech)

/**
 *  @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, CertConfig certConfig, String byteToken, String clientConfig, SDKCallBack.ResultCallback callback)

Example:

//有源比对
BytedFaceLiveManager.getInstance().startFaceCert(NativeFLN.this, new CertConfig(true, 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.7 启动完整认证流程，先做ocr再做有源比对

/**
 * 认证相关配置
 * @param  refSource:  true为有源比对，false为无源比对
 * @param  textSpeech: 文本播报功能 默认值为false，表示不进行语音播报。
 */
class CertConfig(
     boolean refSource,
     boolean textSpeech)

/**
 *  @param  context:      Android上下文
 *  @param  certConfig:   认证相关配置
 *  @param  params:    活体配置参数，具体取值见3.params 活体配置参数介绍介绍
 *  @param  callback: 返回token结果的callback，详细参数见2.3 SDKCallBack.ResultCallback介绍
 *  @return  void
 */
public void beginAuthorizationWithParams(Context context, CertConfig certConfig, Map<String, String> params, SDKCallBack.ResultCallback callback)

Example:

HashMap<String, String> params = new HashMap<>();
params.put("motion_list", mMotionlist.getText().toString());
params.put("liveness_timeout", mLivenessTimeOut.getText().toString());
params.put("fixed_motion_list", mFixedmMotionlist.getText().toString());
params.put("max_liveness_trial", mMaxLivenessTrial.getText().toString());
BytedFaceLiveManager.getInstance().beginAuthorizationWithParams(WelcomeActivity.this, certConfig, 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();
        }
    }
});

1.8 设置自定义用户协议

/**
 *  @param  title:     协议标题
 *  @param  linker:    协议链接SDKCallBack.ResultCallback介绍
 *  @return  void
 */
public void setUserProtocol(String title, String linker)

1.9 自定义样式

1.9.1 获取样式对象单例

public ThemeConfig getThemeConfig()

1.9.2 ThemeConfig 详细说明

public interface ThemeConfig {

    //活体页面进度条进度颜色
    void setFaceLiveProgressColor(int faceLiveProgressColor);
    
    // 活体页面进度条背景色
    void setFaceLiveProgressBgColor(int color);

    //活体页面进度条的宽度, 传px
    void setFaceLiveProgressWidth(float width);

    //活体页面进度条和圆中间的缝隙, 传px
    void setFaceLiveProgressGap(float gap);

    //活体页面背景颜色
    void setFaceLiveScreenBgColor(int color);

    //活体页面文字颜色
    void setFaceLiveTextColor(int color);

    //活体页面文字大小
    void setFaceLiveTextSize(float size);

    //活体页面返回按钮图片，没有设置则使用默认图片
    void setFaceLiveBackImage(Drawable image);
    
		//设置是否使用引导页， true使用，false不使用
    void setUseGuidePage(Boolean bUseGuidePage);
    
	  //设置引导页用户协议，title为标题，linker为链接
    void setGuidePageProtocol(String title, String linker);

    //设置引导页导航栏，showNav是否显示，navTitle导航栏标题
    void setGuidePageProtocolNav(boolean showNav, String navTitle);
    
    //设置身份证页用户协议，title为标题，linker为链接
    void setOcrPageProtocol(String title, String linker);
    
    //设置身份证页导航栏，showNav是否显示，navTitle导航栏标题
    void setOcrPageProtocolNav(boolean showNav, String navTitle);
    
    //设置h5页面的样式，key-value格式，详细格式查看1.9.3（包括引导页以及身份证识别页面）
    void setH5PageStyle(Map<String, String> map);
}

1.9.3 H5PageStyle 详细说明

* 主题色
--theme: rgba(136, 91, 210, 1)
--theme-btn_color: #fff

* 遮罩背景色
--mask_bg-color: rgba(56, 0, 128, 0.4)

* 引导页
--guide-btn_color: $theme-btn_color
--guide-btn_bg-color: $theme
--guide-sub-btn_color: $theme-btn_color
--guide-sub-btn_bg-color: #2b2b2c
--guide-protocol_color: $theme;

* OCR上传身份证页面
--ocr-camera-icon_color: $theme-btn_color;
--ocr-camera-icon_bg-color: $theme;
--ocr-btn_color: $theme-btn_color;
--ocr-btn_bg-color: $theme;

1.9.4 示例

ThemeConfig themeConfig = BytedFaceLiveManager.getInstance().getThemeConfig();
//使用引导页
themeConfig.setUseGuidePage(true);
//设置引导页用户协议
themeConfig.setGuidePageProtocol("自定义协议","https://www.baidu.com");
//设置倒计时背景色
themeConfig.setFaceLiveProgressBgColor(Color.parseColor("#E8E8E8"));
//设置倒计时进度条颜色
themeConfig.setFaceLiveProgressColor(Color.parseColor("#2A90D7"));

//设置引导页和身份证页面样式
HashMap<String, String> h5PageStyleMap = new HashMap<>();
h5PageStyleMap.put("--theme", "rgba(136, 91, 210, 1)");
h5PageStyleMap.put("--theme-btn_color", "#fff");
themeConfig.setH5PageStyle(h5PageStyle);

1.10 自定义权限请求

/**
 *  @param  SDKCallBack.RequestPermissionsCallback:      权限请求的回调函数
 *  @return  void
 */
public void setRequestPermissionsCallback(SDKCallBack.RequestPermissionsCallback callback)

Example:

BytedFaceLiveManager.getInstance().setRequestPermissionsCallback(new SDKCallBack.RequestPermissionsCallback() {
                                        @Override
                                        public void requestPermissions(Activity content,  String[] permissions, SDKCallBack.RequestPermissionsResultCallback resultCallback) {
                                            Toast.makeText(mContext, "自定义权限请求", Toast.LENGTH_SHORT).show();                                    PermissionUtils.checkPermissionAndStartFaceLive(content, new PermissionCallback() {
                                                @Override
                                                public void allow() {
                                                    Toast.makeText(mContext, "自定义权限请求成功", Toast.LENGTH_SHORT).show();
                                                    resultCallback.allow();
                                                }

                                                @Override
                                                public void deny() {
                                                    Toast.makeText(mContext, "自定义权限请求拒绝", Toast.LENGTH_SHORT).show();
                                                    resultCallback.deny();
                                                }
                                            });
                                    
                                        }
                                    });

2. callback

2.1 BytedCertUploadVideoFinishBlock

/**
	 *  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

/**
	 *  onOcrFinish参数
	 *  @param  errorCode     错误码
	 *  @param errorMsg      错误信息    
	 *  @param identityCode  身份证id
	 *  @paramd entityName   姓名
	 */
	interface OcrCallback {
	    void onOcrFinish(int errorCode, String errorMsg, String identityCode, String identityName);
	}

2.3 SDKCallBack.ResultCallback

返回数据jsonData的数据格式参考SDK返回内容说明中"服务端认证返回数据"章节的'jsonData'字段。
注意：这里已把jsonData字符串解析成了JSONObject格式

/**
	 *  onResultFinish
   *	errorCode， 错误码
   *	errorMsg，  错误信息
   *	jsonData，  返回数据, 详细数据格式参考人脸核身服务端api的返回字段中的"resp_data"
	 */
	interface ResultCallback {
	    void onResultFinish(int errorCode, String errorMsg, JSONObject jsonData);
	}

2.4 SDKCallBack.BytedTokenCallback

/**
 * onResultFinish参数
 *  @param  errorCode     错误码
 *  @param errorMsg      错误信息    
 *  @param bytedToken，   返回的bytenToken值
 *  @paramd client_config  客户端配置，原样传给startFaceCert即可
 */
interface BytedTokenCallback {
    void onResultFinish(int errorCode, String errorMsg, String bytedToken, String client_config);
}

2.5 SDKCallBack.RequestPermissionsCallback

//权限回调结果
interface RequestPermissionsResultCallback {
		//权限允许
		void allow();
		//权限拒绝
		void deny();
}
    
//权限回调
interface RequestPermissionsCallback {
		//content 上下文
		//permissions 需要请求的权限
		//resultCallback 请求结果回调
		void requestPermissions(Activity content, String[] permissions, RequestPermissionsResultCallback resultCallback);
    }

3. params 活体配置参数介绍

key	说明
motion_list	活体动作列表，以','隔开，例"0,1,2" //0:"眨眼",1:"张嘴",2:"点头",3:"摇头"
motion_count	需要的活体动作个数，从motion_list中选择motion_count个，需要小于等于 motion_list中的个数
liveness_timeout	端上活体超时时长，可选范围： [5, 60]，默认：10
fixed_motion_list	固定一定需要下发的动作列表, 取值同motion_list
max_liveness_trial	端上动作活体最大尝试次数, 可选范围：[1, 100]，默认：10

错误码

特别说明：50000+以上的为服务端透传的错误码，具体可以查看服务端错误码

错误代码	说明
0	成功
-2	客户端上内部错误。一般出现在集成阶段，需检查logcat运行时的日志排查问题原因。
-4	您手动退出或因识别失败次数大于4次，导致客户端默认退出。
-1000	网络异常，请稍后再试
-1001	未知错误
-1002	活体中断
-1003	活体识别失败，请再试一次
-1004	算法初始化失败
-1005	活体参数设置失败
-1006	用户取消操作
-1007	用户取消证件识别
-1101	超过活体最大次数
-3001	网络数据包解析失败
-3002	请退出多屏模式，再重试一次
-3003	无法使用相机，请检查是否打开相机权限
-3006	相册图片获取失败
-3007	拍照失败
-5021	比对失败，请确认是本人
50000+	50000以上错误码，为透传服务端的错误码，请参考人脸核身服务端api的错误码说明

身份认证

Android版本

Android SDK

Demo

1.将BytedCertSdk-release.aar 引入您的工程中

a.拷贝BytedCertSdk-release.aar 到您工程的libs目录下

b.配置gradle, build.gradle中加入flatDir，并在dependencies中加入implementation(name:'BytedCertSdk-release', ext:'aar')

2.AndroidManifest.xml添加以下权限权

3.如果开启了混淆（minifyEnabled true），需要在混淆文件中添加以下配置

4.其他配置

相关依赖

1. 入口类BytedFaceLiveManager

1.1 获取BytedFaceLiveManager单例

1.2 设置鉴权参数

1.3 配置视频录制参数

1.4 ocr识别接口

1.5 获取token接口

1.6 启动活体

1.7 启动完整认证流程，先做ocr再做有源比对

1.8 设置自定义用户协议

1.9 自定义样式

1.9.1 获取样式对象单例

1.9.2 ThemeConfig 详细说明

1.9.3 H5PageStyle 详细说明

1.9.4 示例

1.10 自定义权限请求

2. callback

2.1 BytedCertUploadVideoFinishBlock

2.2 SDKCallBack.OcrCallback

2.3 SDKCallBack.ResultCallback

2.4 SDKCallBack.BytedTokenCallback

2.5 SDKCallBack.RequestPermissionsCallback

3. params 活体配置参数介绍

错误码