tencent cloud

人脸核身

Android 接口概述

下载
聚焦模式
字号
最后更新时间: 2026-10-27 14:31:49
本文档已由 AI 辅助审校

Token 模式(公有云一站式接入)下,Android 端文字识别 SDK 主要涉及的类有 OcrOverseasCloudKit、OcrCloudConfig、IOcrCloudResultListener、OcrCloudResult、OcrCloudError、OcrCloudStatus、LanguageStyle、CustomConfigUi,下面对其支持的 API 做出详细说明。
说明:
与"全流程接入(OcrSDKKit)"模式的区别:
业务方只需保管 sdkToken,不再持有/下发临时密钥(SecretId / SecretKey / Token)。
证件类型、采集证件照片的模式、是否允许相册上传等业务侧参数全部由后端通过 serverParamInfo 下发,SDK 内部解密并应用,前端不再硬编码。
SDK 不再向调用方返回识别 JSON,仅回调"识别完成"状态(OcrCloudStatus.SUCCESS),由业务方在自己的服务端按 sdkToken 拉取结构化结果。

OcrOverseasCloudKit

OcrOverseasCloudKit 是 Token 模式公有云 OCR 识别的对外接口类,所有 token 模式的功能均集中在此类中。
API
功能描述
创建 OcrOverseasCloudKit 的单例
init()
初始化 SDK
刷新/更新 SDK 配置信息
启动公有云 OCR 识别(一次调用完成采集 + 上传)
release()
主动释放资源
获取当前缓存的 sdkToken
同步采集设备/应用元数据并加密,获取 token 时需要上传到服务端
获取当前 SDK 的版本号
注册采集事件监听器

getInstance()

public static OcrOverseasCloudKit getInstance()

功能描述:创建 OcrOverseasCloudKit 的单例。
返回结果:OcrOverseasCloudKit 的单例对象。


init()

public void init(Context context)

功能描述:初始化 SDK。必须在 startCloudOcr 之前调用一次,否则 startCloudOcr 会通过 IOcrCloudResultListener#onFailed 返回 errorCode=-1、errorMsg="Please call init() before startCloudOcr"。
传入参数:
参数类型
参数名称
参数含义
Context
context
应用的上下文信息

updateConfig()

public void updateConfig(OcrSDKConfig config)

功能描述:在 SDK 已初始化的前提下,主动覆盖底层 SDK 配置(一般无需调用,startCloudOcr 内部会基于 serverParamInfo 自动构建并应用底层 OcrSDKConfig)。
传入参数:
参数类型
参数名称
参数含义
OcrSDKConfig
config
新的底层 SDK 配置对象

startCloudOcr()

public void startCloudOcr(Activity activity,
OcrCloudConfig config,
IOcrCloudResultListener listener)

功能描述:启动公有云 OCR 识别。SDK 内部完成以下流程,业务方无需感知:
1. 校验 sdkToken / serverParamInfo 非空;
2. 解密 serverParamInfo,解析出本次任务的 ocrModeType / cardSide / nationality / cardType / maxImageSize / allowUploadPhoto / cardAlgorithmConfig 等服务端下发参数;
3. 根据 cardSide 自动选择"单面采集"或"双面采集"(BOTH 时启动双面采集);
4. 采集结束后将 jpg 图片以加密二进制(application/octet-stream)形式上传至 /ocr/v1/ocr/recognize;
5. 上传成功并解析后端返回后,通过 IOcrCloudResultListener#onSuccess 回调 OcrCloudStatus.SUCCESS;任意环节失败则通过 onFailed 回调结构化的 OcrCloudError。

传入参数:
参数类型
参数名称
参数含义
Activity
activity
启动 OCR 默认界面的当前 Activity 对象
config
Token 模式下的启动配置(包含 sdkToken 与 serverParamInfo 等)
listener
用于接收识别状态/错误的回调对象

release()

public void release()

功能描述:主动释放资源,可在退出业务页面或需要清理资源时调用。release 后单例会被置空,下次调用 getInstance() 会重新创建实例,需要重新 init()。


getCurrentToken()

public String getCurrentToken()

功能描述:获取当前缓存的 sdkToken。
返回结果:当前 OcrCloudConfig 中的 sdkToken;若尚未发起任何调用,返回空字符串。


createMetaData()

public String createMetaData()

功能描述:同步采集当前设备/应用的元数据,并使用 SDK 内置算法加密,便于业务方在向自己的后端换取/查询 sdkToken 时一并上送。


getVersion()

public String getVersion()

功能描述:获取 SDK 当前的版本号。
返回结果:当前 SDK 的版本信息。


setCloudEventListener()

public void setCloudEventListener(IOcrCloudEventListener listener)

功能描述:注册采集事件监听器,用于监听 OCR 采集过程中的 UI 生命周期和参数透传事件。可在 startCloudOcr 之前调用。
传入参数:
参数类型
参数名称
参数含义
listener
采集事件监听器,传 null 可取消注册
注意:
此接口独立于全流程模式的 OcrEventListener,仅暴露 onMainViewCreate / onMainViewDestroy / onEventParamMap 三个回调,不暴露相机等内部事件。onCameraOpenSuccess 回调由 SDK 内部处理(图灵盾等逻辑),不对外转发。

OcrCloudConfig

OcrCloudConfig 是 Token 模式启动 OCR 时需要传入的启动配置实体类,采用 javabean set 的方式进行参数配置。
类型
名称
含义
默认值
String
sdkToken
必填。SDK 业务 token,由业务方后端调用云端接口换取,作为本次识别请求的唯一标识
空(必填,不传将直接回调失败)
String
serverParamInfo
必填。由业务方后端获取并透传给 SDK 的加密参数串,SDK 内部解密后用于驱动本次采集与识别
空(必填,不传将直接回调失败)
customConfigUi
自定义 UI 配置
null
languageStyle
使用的语言
LanguageStyle.AUTO
String
languageCode
扩展的多语言语言码(配合 CUSTOMIZE_LANGUAGE 使用)
空
boolean
showBestImgConfirmDialog
是否显示最佳帧确认弹窗
false
boolean
useSystemClip
是否使用系统的裁剪
false
boolean
openClipImage
选择图片时是否启用采集功能
true
boolean
disableSystemRecordScreen
是否关闭录屏/截屏(开启 FLAG_SECURE)
false
boolean
openLog
是否打开日志
true
boolean
showPrivacyPolicyDialog
是否显示隐私政策弹窗
true

IOcrCloudEventListener

公有云 OCR 采集过程的事件回调接口,用于监听采集过程中的 UI 生命周期和参数透传事件。
/**
* 公有云OCR采集过程的事件回调接口
*/
public interface IOcrCloudEventListener {

/**
* OCR识别的主View被创建的回调
*
* @param mainView 主View
*/
void onMainViewCreate(View mainView);

/**
* 界面被回收的回调
*/
void onMainViewDestroy();

/**
* 额外的参数透传
*
* @param map 透传参数
*/
void onEventParamMap(HashMap<String, Object> map);
}


IOcrCloudResultListener

公有云 OCR 识别结果的回调类,用于接收识别状态以及错误异常。
/**
* 公有云OCR识别结果的回调接口
*/
public interface IOcrCloudResultListener {

/**
* 识别成功回调
*
* @param result 成功结果,包含sdkToken和状态
*/
void onSuccess(OcrCloudResult result);

/**
* 识别失败回调
*
* @param error 失败结果,包含sdkToken、错误码(int)和错误信息
*/
void onFailed(OcrCloudError error);
}
说明:
Token 模式下,SDK 不会回调结构化的 OCR 识别 JSON。业务方收到 onSuccess 后,应使用 result.getSdkToken() 在自己的服务端向云端拉取最终的结构化识别结果。


OcrCloudResult

成功回调时携带的数据。
类型
名称
含义
默认值
String
sdkToken
透传回调用方的 sdkToken
空
status
识别状态(当前仅 SUCCESS,表示后端已出结果)
null

OcrCloudError

失败回调时携带的数据。

类型
名称
含义
默认值
String
sdkToken
透传回调用方的 sdkToken
空
int
errorCode
错误码(int 类型,详见错误码章节)
-1
String
errorMsg
错误信息
null

OcrCloudStatus

识别状态枚举。

OcrCloudStatus 取值
代表含义
SUCCESS
识别完成,后端已生成最终结果

LanguageStyle

LanguageStyle 是一个枚举类型,列举了支持的语言类型。

LanguageStyle 类型
代表含义
AUTO
跟随系统语言
ENGLISH
英文
SIMPLIFIED_CHINESE
简体中文
TRADITIONAL_CHINESE
繁体中文
BAHASA
印尼语
CUSTOMIZE_LANGUAGE
自定义语言

CustomConfigUi

自定义 UI 的配置类,与"全流程接入"模式共用同一个类,常用属性如下,可通过 javabean set 方式设置(完整字段请参考 SDK 头文件):

类型
名称
含义
boolean
isShowTitleBar
设置是否显示默认界面的标题栏
String
titleBarText
设置标题栏显示的文字内容
int
titleColor
设置标题栏背景颜色(0xFFFFFF 类型)
int
cardFrameColor
设置卡片预览框四角选中时的颜色
int
imageSelectResId
默认界面图库选择按钮的图标资源 id
int
lightImageOnResId
打开闪光灯的图标资源 id
int
lightImageOffResId
关闭闪光灯的图标资源 id
int
takePicturesResId
主动拍照按钮的图标资源 id
int
backActionIconResId
返回按钮的图标资源 id
boolean
isRemoveAlbum
是否隐藏相册选取按钮(注意:服务端下发 allowUploadPhoto=false 时 SDK 会自动置为 true,覆盖业务方传值)
boolean
isRemoveFlash
是否隐藏闪光灯按钮
boolean
isLandscape
是否横屏
boolean
isShowTips
是否显示 tips 框
String
showTipsText
tips 框的文字内容
int
portraitLayoutResId
竖屏自定义布局资源 id
int
landscapeLayoutResId
横屏自定义布局资源 id
boolean
showCustomPermissionDialog
是否显示自定义权限对话框
String
customPermissionDialogTitle
自定义权限对话框标题
String
customPermissionDialogDetail
自定义权限对话框详情


接入流程

sequenceDiagram
participant App as 业务 App
participant Backend as 业务后端
participant SDK as OcrOverseasCloudKit
participant Cloud as OCR 云端

App->>SDK: getInstance().init(context)
App->>SDK: 调用createMetaData()获取元数据
SDK-->>App:返回metaData的数据
App->>Backend: 上传metaData并申请 sdkToken / serverParamInfo
Backend-->>App: 下发 sdkToken + serverParamInfo
App->>SDK: startCloudOcr(activity, OcrCloudConfig, listener)
SDK->>SDK: 解密 serverParamInfo,决定单/双面采集
SDK->>SDK: 启动相机采集,得到 jpg 最佳帧
SDK->>Cloud: POST OCR最佳帧进行识别
Cloud-->>SDK: 识别完成应答
SDK-->>App: onSuccess(OcrCloudResult{status=SUCCESS, sdkToken})
App->>Backend: 凭 sdkToken 拉取结构化识别结果


接入示例

// Step 1:在 Application 或业务页面 onCreate 中初始化(仅需一次)
OcrOverseasCloudKit.getInstance().init(getApplicationContext());

// Step 2:向业务后端申请 sdkToken / serverParamInfo 之前,
// 先用 createMetaData() 同步采集设备/应用元数据(SDK 内部加密),并随申请请求一并上送。
// 该字段与服务端协议保持一致,便于后端在调用云端 CreateOCRToken 时一并透传,用于风控与参数校验。
String metaData = OcrOverseasCloudKit.getInstance().createMetaData();
// TODO: 将 metaData 作为请求参数(如字段名 metaData)上送给业务后端,参考 app-public 的
// TokenApiHelper#applyToken 实现:body.put("metaData", OcrOverseasCloudKit.getInstance().createMetaData())

// Step 3:从业务后端换取 sdkToken / serverParamInfo
String sdkToken = "..."; // 由业务后端下发
String serverParamInfo = "..."; // 由业务后端下发,密文字符串

// Step 4:构造启动配置
OcrCloudConfig config = new OcrCloudConfig();
config.setSdkToken(sdkToken);
config.setServerParamInfo(serverParamInfo);
config.setLanguageStyle(LanguageStyle.SIMPLIFIED_CHINESE);
config.setShowPrivacyPolicyDialog(true);
// 可选:自定义 UI
CustomConfigUi customConfigUi = new CustomConfigUi();
customConfigUi.setShowTitleBar(true);
customConfigUi.setTitleBarText("身份证识别");
config.setCustomConfigUi(customConfigUi);

// 可选:注册采集事件监听器
OcrOverseasCloudKit.getInstance().setCloudEventListener(new IOcrCloudEventListener() {
@Override
public void onMainViewCreate(View mainView) {
// 主View创建,可在此添加自定义视图
}

@Override
public void onMainViewDestroy() {
// 主View销毁
}

@Override
public void onEventParamMap(HashMap<String, Object> map) {
// 参数透传
}
});

// Step 5:启动识别
OcrOverseasCloudKit.getInstance().startCloudOcr(activity, config,
new IOcrCloudResultListener() {
@Override
public void onSuccess(OcrCloudResult result) {
// 识别完成,业务方可凭 result.getSdkToken() 在服务端拉取结构化结果
if (result.getStatus() == OcrCloudStatus.SUCCESS) {
String token = result.getSdkToken();
// TODO: 通知业务后端拉取识别结果
}
}

@Override
public void onFailed(OcrCloudError error) {
// 错误处理:error.getErrorCode() / error.getErrorMsg()
}
});

// Step 5:在合适的时机释放资源(例如业务页面 onDestroy)
OcrOverseasCloudKit.getInstance().release();


错误码

OcrCloudError#errorCode 为 int 类型,由 SDK 内部统一从字符串错误码映射而来(实现见 OcrSdkNetSender#mapErrorCodeToInt)。常见错误码如下:
错误码
常量名
含义
-1
-
参数校验失败(如 sdkToken / serverParamInfo 为空、Activity 为空、未先调用 init() 等)
100100
TXY_SDK_PARAMETER_ERROR_CODE
参数异常
100102
TXY_SDK_NETWORK_ERROR_CODE
网络异常
100103
TXY_SDK_CAMERA_PERMISSION_ERROR_CODE
摄像头权限异常
200101
TXY_SDK_USER_CANCEL_CODE
用户主动取消识别
300101
TXY_SDK_VERIFY_MODEL_INIT_FAIL
模型/SDK 初始化异常
300102
TXY_SDK_VERIFY_SERVER_FAIL
服务解析异常(含网络超时、密文解析失败、未知错误兜底)
300103
TXY_SDK_API_SIGNATURE_FAIL
签名失败
300104
TXY_SDK_CAMERA_ERROR_CODE
摄像头异常
300105
TXY_SDK_YTCONFIG_INIT_ERROR_CODE
初始化配置失败
300106
TXY_SDK_OCR_IMAGE_NULL
图片异常空
300107
TXY_SDK_OCR_AUTH_FAIL
license 授权失败
300108
TXY_SDK_SYSTEM_VERSION_LOW
系统版本过低
300109
TXY_SDK_AUTO_MODE_TIME_OUT
自动模式超时(未捕获到图片)
300110
TXY_SDK_INNER_SDK_OCR_ERROR
SDK 内部错误
300111
TXY_SDK_INNER_SDK_OCR_ERROR_CLIP_ERROR
SDK 内部图片裁剪异常
300112
TXY_SDK_OCR_ERROR_CARD_TYPE_ERROR
卡证类型不匹配
300113
TXY_SDK_OCR_WARN_ERROR_MANY_TIME
OCR 失败:告警次数过多
错误码
含义
400100
触发指定拦截的告警码
400101
证件类型不匹配(传入的证件类型与指定类型不一致)
400102
证件正反面不符(传入的证件面与选择不同)
400103
证件占比过小(卡证在照片中占比太小)
400104
检测到多张证件
400105
OCR 识别失败
400106
证件信息校验失败
400107
入参存在错误
400108
内部服务错误
400109
服务未开通 / 账号欠费 / 资源包耗尽
400110
请求频率超限(触发限流)
400111
图片尺寸或文件大小无效
400112
文件解析失败
说明:
业务接口若直接回传纯数字字符串(例如服务端 resultCode 为 "300102"),SDK 将原值透传为 errorCode,其语义请以服务端约定为准。

注意事项

1. 必须先 init(),再 startCloudOcr():init 内部会完成底层 SDK 初始化与埋点初始化(native 库 YTImageRefinerPub 在 getInstance() 创建单例时加载);未初始化直接调用启动接口将通过 onFailed 回调 errorCode=-1 与说明文案。
2. sdkToken 与 serverParamInfo 必须由业务方后端下发:前端不要自行解析 / 复用 serverParamInfo,每次新启动建议都向后端重新换取,避免使用过期数据。
3. OcrOverseasCloudKit 与 OcrSDKKit 不要混用:Token 模式与全流程模式的网络协议、回调语义不同,同一业务流程中只选其一。
4. release() 后单例会被置空:再次使用需重新 getInstance() 并 init()。
5. 网络默认超时 60s:超时后 SDK 主动停止当前请求,并通过 onFailed 回调 errorCode=300102、errorMsg="net connect timeout"。

帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈