serverParamInfo 下发,SDK 内部解密并应用,前端不再硬编码。OcrCloudStatus.SUCCESS),由业务方在自己的服务端按 sdkToken 拉取结构化结果。API | 功能描述 |
创建 OcrOverseasCloudKit 的单例 | |
初始化 SDK | |
刷新/更新 SDK 配置信息 | |
启动公有云 OCR 识别(一次调用完成采集 + 上传) | |
主动释放资源 | |
获取当前缓存的 sdkToken | |
同步采集设备/应用元数据并加密,获取 token 时需要上传到服务端 | |
获取当前 SDK 的版本号 | |
注册采集事件监听器 |
public static OcrOverseasCloudKit getInstance()
public void init(Context context)
startCloudOcr 之前调用一次,否则 startCloudOcr 会通过 IOcrCloudResultListener#onFailed 返回 errorCode=-1、errorMsg="Please call init() before startCloudOcr"。参数类型 | 参数名称 | 参数含义 |
Context | context | 应用的上下文信息 |
public void updateConfig(OcrSDKConfig config)
startCloudOcr 内部会基于 serverParamInfo 自动构建并应用底层 OcrSDKConfig)。参数类型 | 参数名称 | 参数含义 |
OcrSDKConfig | config | 新的底层 SDK 配置对象 |
public void startCloudOcr(Activity activity,OcrCloudConfig config,IOcrCloudResultListener listener)
sdkToken / serverParamInfo 非空;serverParamInfo,解析出本次任务的 ocrModeType / cardSide / nationality / cardType / maxImageSize / allowUploadPhoto / cardAlgorithmConfig 等服务端下发参数;cardSide 自动选择"单面采集"或"双面采集"(BOTH 时启动双面采集);application/octet-stream)形式上传至 /ocr/v1/ocr/recognize;IOcrCloudResultListener#onSuccess 回调 OcrCloudStatus.SUCCESS;任意环节失败则通过 onFailed 回调结构化的 OcrCloudError。参数类型 | 参数名称 | 参数含义 |
Activity | activity | 启动 OCR 默认界面的当前 Activity 对象 |
config | Token 模式下的启动配置(包含 sdkToken 与 serverParamInfo 等) | |
listener | 用于接收识别状态/错误的回调对象 |
public void release()
getInstance() 会重新创建实例,需要重新 init()。public String getCurrentToken()
OcrCloudConfig 中的 sdkToken;若尚未发起任何调用,返回空字符串。public String createMetaData()
public String getVersion()
public void setCloudEventListener(IOcrCloudEventListener listener)
startCloudOcr 之前调用。参数类型 | 参数名称 | 参数含义 |
listener | 采集事件监听器,传 null 可取消注册 |
OcrEventListener,仅暴露 onMainViewCreate / onMainViewDestroy / onEventParamMap 三个回调,不暴露相机等内部事件。onCameraOpenSuccess 回调由 SDK 内部处理(图灵盾等逻辑),不对外转发。类型 | 名称 | 含义 | 默认值 |
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 |
/*** 公有云OCR采集过程的事件回调接口*/public interface IOcrCloudEventListener {/*** OCR识别的主View被创建的回调** @param mainView 主View*/void onMainViewCreate(View mainView);/*** 界面被回收的回调*/void onMainViewDestroy();/*** 额外的参数透传** @param map 透传参数*/void onEventParamMap(HashMap<String, Object> map);}
/*** 公有云OCR识别结果的回调接口*/public interface IOcrCloudResultListener {/*** 识别成功回调** @param result 成功结果,包含sdkToken和状态*/void onSuccess(OcrCloudResult result);/*** 识别失败回调** @param error 失败结果,包含sdkToken、错误码(int)和错误信息*/void onFailed(OcrCloudError error);}
onSuccess 后,应使用 result.getSdkToken() 在自己的服务端向云端拉取最终的结构化识别结果。类型 | 名称 | 含义 | 默认值 |
String | sdkToken | 透传回调用方的 sdkToken | 空 |
status | 识别状态(当前仅 SUCCESS,表示后端已出结果) | null |
类型 | 名称 | 含义 | 默认值 |
String | sdkToken | 透传回调用方的 sdkToken | 空 |
int | errorCode | -1 | |
String | errorMsg | 错误信息 | null |
OcrCloudStatus 取值 | 代表含义 |
SUCCESS | 识别完成,后端已生成最终结果 |
LanguageStyle 类型 | 代表含义 |
AUTO | 跟随系统语言 |
ENGLISH | 英文 |
SIMPLIFIED_CHINESE | 简体中文 |
TRADITIONAL_CHINESE | 繁体中文 |
BAHASA | 印尼语 |
CUSTOMIZE_LANGUAGE | 自定义语言 |
类型 | 名称 | 含义 |
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 | 自定义权限对话框详情 |
sequenceDiagramparticipant App as 业务 Appparticipant Backend as 业务后端participant SDK as OcrOverseasCloudKitparticipant Cloud as OCR 云端App->>SDK: getInstance().init(context)App->>SDK: 调用createMetaData()获取元数据SDK-->>App:返回metaData的数据App->>Backend: 上传metaData并申请 sdkToken / serverParamInfoBackend-->>App: 下发 sdkToken + serverParamInfoApp->>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 / serverParamInfoString sdkToken = "..."; // 由业务后端下发String serverParamInfo = "..."; // 由业务后端下发,密文字符串// Step 4:构造启动配置OcrCloudConfig config = new OcrCloudConfig();config.setSdkToken(sdkToken);config.setServerParamInfo(serverParamInfo);config.setLanguageStyle(LanguageStyle.SIMPLIFIED_CHINESE);config.setShowPrivacyPolicyDialog(true);// 可选:自定义 UICustomConfigUi customConfigUi = new CustomConfigUi();customConfigUi.setShowTitleBar(true);customConfigUi.setTitleBarText("身份证识别");config.setCustomConfigUi(customConfigUi);// 可选:注册采集事件监听器OcrOverseasCloudKit.getInstance().setCloudEventListener(new IOcrCloudEventListener() {@Overridepublic void onMainViewCreate(View mainView) {// 主View创建,可在此添加自定义视图}@Overridepublic void onMainViewDestroy() {// 主View销毁}@Overridepublic void onEventParamMap(HashMap<String, Object> map) {// 参数透传}});// Step 5:启动识别OcrOverseasCloudKit.getInstance().startCloudOcr(activity, config,new IOcrCloudResultListener() {@Overridepublic void onSuccess(OcrCloudResult result) {// 识别完成,业务方可凭 result.getSdkToken() 在服务端拉取结构化结果if (result.getStatus() == OcrCloudStatus.SUCCESS) {String token = result.getSdkToken();// TODO: 通知业务后端拉取识别结果}}@Overridepublic 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,其语义请以服务端约定为准。init(),再 startCloudOcr():init 内部会完成底层 SDK 初始化与埋点初始化(native 库 YTImageRefinerPub 在 getInstance() 创建单例时加载);未初始化直接调用启动接口将通过 onFailed 回调 errorCode=-1 与说明文案。serverParamInfo,每次新启动建议都向后端重新换取,避免使用过期数据。OcrOverseasCloudKit 与 OcrSDKKit 不要混用:Token 模式与全流程模式的网络协议、回调语义不同,同一业务流程中只选其一。release() 后单例会被置空:再次使用需重新 getInstance() 并 init()。onFailed 回调 errorCode=300102、errorMsg="net connect timeout"。文档反馈