tencent cloud

人脸核身

iOS 接口概述

下载
聚焦模式
字号
最后更新时间: 2026-10-29 11:05:36
本文档已由 AI 辅助审校
iOS 端文字识别 SDK 主要涉及的类有 OcrOverseasCloudKit、OcrCloudConfig、OcrCloudResult、OcrCloudError、OcrOverseasCustomConfigUI,下面对其支持的 API 做出详细说明。


OcrOverseasCloudKit

OcrOverseasCloudKit 是 SDK 的对外入口类,采用 Token 模式,所有识别功能集中在此类中。
API
功能描述
获取 OcrOverseasCloudKit 单例
释放 SDK 资源
获取 SDK 版本号
初始化 SDK
获取 SDK 元数据
启动 Token 模式识别

sharedInstance()

+ (nonnull instancetype)sharedInstance;
功能描述:获取 OcrOverseasCloudKit 单例对象。
返回结果:OcrOverseasCloudKit 单例。


clearInstance()

- (void)clearInstance;
功能描述:主动释放 SDK 资源,可在退出应用或需要清理时调用。


getVersion()

- (NSString *)getVersion;
功能描述:获取当前 SDK 版本号字符串。
返回结果:版本号字符串,如 "4.0.2"。


initWithViewController()

- (void)initWithViewController:(UIViewController *)viewController;
功能描述:初始化 SDK,传入承载识别页面的 ViewController。
传入参数:
参数类型
参数名称
参数含义
UIViewController
viewController
承载识别页面的 ViewController


createMetaData()

+ (NSString *)createMetaData;
功能描述:获取设备元数据字符串,在申请 sdkToken 时作为入参传入。
返回结果:元数据 JSON 字符串(Base64 编码)。


startCloudOcr:withSucceedBlock:withFailedBlock:

- (void)startCloudOcr:(OcrCloudConfig *_Nonnull)cloudConfig
withSucceedBlock:(OcrCloudSucceedBlock _Nonnull)onSucceed
withFailedBlock:(OcrCloudFailedBlock _Nonnull)onFailed;
功能描述:启动 Token 模式 OCR 识别。SDK 完成采集后通过成功回调返回 sdkToken,宿主 App 凭此 Token 从服务端拉取最终识别结果。
传入参数:
参数类型
参数名称
参数含义
cloudConfig
Token 模式配置对象
OcrCloudSucceedBlock
onSucceed
采集成功回调,返回 OcrCloudResult
OcrCloudFailedBlock
onFailed
识别失败回调,返回 OcrCloudError


OcrCloudConfig

OcrCloudConfig 是 Token 模式下启动 SDK 时传入的配置对象。
类型
名称
含义
是否必填
NSString
sdkToken
业务 Token,由宿主 App 从服务端获取,用于串联整个识别业务
必填
NSString
serverParamInfo
服务端参数信息
必填
customConfigUI
自定义 UI 配置
可选


OcrCloudResult

OcrCloudResult 是 Token 模式成功回调返回的结果对象。
类型
名称
含义
NSString
sdkToken
业务 Token,用于宿主 App 从服务端拉取最终识别结果


OcrCloudError

OcrCloudError 是 Token 模式失败回调返回的错误对象。
类型
名称
含义
NSString
sdkToken
业务 Token(可用于问题定位)
NSInteger
errorCode
错误码,参见 错误码
NSString
errorMsg
错误信息描述


OcrOverseasCustomConfigUI

OcrOverseasCustomConfigUI 是启动 SDK 时可选传入的 UI 配置类。
类型
名称
含义
默认值
id<OcrOverseasViewDelegate>
delegate
UI 相关代理
nil
landscapeMode
横屏模式配置
OcrLandscapeModePortrait
BOOL
isShowTips
是否显示中间提示语
YES
NSString
tipsShowText
中间提示语内容(限 15 个中文字)
"请避免识别内容折角、遮挡和过暗"
UIImage
takePictureImage
拍照按钮图标 80×80
默认图标
UIImage
lightONImage
打开手电筒按钮图标 40×40
默认图标
UIImage
lightOFFImage
关闭手电筒按钮图标 40×40
默认图标
UIImage
albumImage
相册按钮图标 40×40
默认图标
BOOL
isShowLight
是否显示手电筒按钮
YES
languageType
设置当前使用语言
OCR_DEFAULT
BOOL
openClipImage
开启相册图片裁剪页面
NO
BOOL
supportOnlyAlbumMode
无相机权限时支持仅使用相册
NO
BOOL
isShowPrivacyAgreementDialog
是否显示隐私协议弹窗
YES
BOOL
isForbidAnima
隐藏拉起/退出 OCR 转场动画
YES
CGFloat
cardFrameWidth
识别框四个角边线宽度
2.0
BOOL
showBestImgConfirmDialog
最佳帧确认弹窗(仅 OCR_DETECT_AUTO 模式)
NO
NSArray<UIColor *>
custRectColorArr
识别框颜色数组 [normal, error, pass]
nil
NSArray<UIColor *>
custTipsColorArr
提示语颜色数组 [normal, error, pass]
nil
UIFont
custTipsFont
自定义提示语字体
nil
NSString
ocrSDKBundlePath
OcrSDK.bundle 文件路径,默认从 main bundle 读取
nil
NSString
ocrModelPath
OcrModel.bundle 文件路径,默认从 main bundle 读取
nil
NSString
custBundlePath
自定义 UI bundle 路径
nil
NSString
custLanguageBundlePath
自定义多语言 bundle 路径
nil
NSString
custLanguageFile
自定义语言文件名(如 en.lproj)
nil
CGFloat
custRectScaleY
识别框 Y 轴偏移百分比,仅竖屏有效
0.21
CGFloat
custRectScaleX
识别框 X 轴偏移百分比
0.01


OcrLandscapeMode

OcrLandscapeMode 枚举类型,列举了支持的横屏模式:
类型
代表含义
适用场景
OcrLandscapeModePortrait
竖屏(默认)
竖屏场景下识别
OcrLandscapeModeUIRotateLandscapeLeft
UI 旋转横屏 - 前置相机在左侧
项目仅支持竖屏,以页面旋转方式实现横屏
OcrLandscapeModeUIRotateLandscapeRight
UI 旋转横屏 - 前置相机在右侧
项目仅支持竖屏,以页面旋转方式实现横屏
OcrLandscapeModeDeviceLandscapeLeft
设备旋转横屏 - 前置相机在左侧
项目支持横屏,设备固定旋转方向
OcrLandscapeModeDeviceLandscapeRight
设备旋转横屏 - 前置相机在右侧
项目支持横屏,设备固定旋转方向


OcrLanguageType

OcrLanguageType 枚举类型,列举了语言设置:
类型
代表含义
OCR_DEFAULT
跟随系统
OCR_ZH_HANS
中文简体
OCR_ZH_HANT
中文繁体
OCR_EN
英文
OCR_CUSTOMIZE_LANGUAGE
定制语言
OCR_INDONESIA
印尼语


错误码

OcrCloudError.errorCode 错误码说明:
错误码
含义
100100
参数异常
100102
网络异常
100103
摄像头权限异常
101000
识别失败
200101
用户主动取消识别
300101
初始化模型失败
300102
服务端响应解析异常
300103
API 签名失败
300104
摄像头异常
300105
SDK 初始化配置失败
300106
图片数据为空
300107
授权失败
300108
系统版本过低(低于 iOS 11.0)
300109
自动模式超时
300110
SDK 内部错误
300112
卡证类型不匹配
300113
连续识别失败次数过多
300114
视频录制失败
300115
识别过程中切换了应用
400100
触发指定拦截的告警码
400101
用户传入的证件类型和指定证件类型不一致
400102
用户传入的证件面和选择的不同
400103
用户传入照片中卡证占比太小
400104
用户传入的照片中包括多张卡证照片
400105
OCR 识别失败
400106
卡证信息校验失败
400107
入参存在错误
400108
内部服务错误
400109
服务未开通 / 账号欠费 / 资源包耗尽 / 计费异常
400110
触发限流
400111
文件 size 太大或无效
400112
文件解析失败


识别结果回调

Token 模式的回调定义如下:
/// Token 模式成功回调
/// @param result 成功结果,包含 sdkToken
typedef void (^OcrCloudSucceedBlock)(OcrCloudResult *_Nonnull result);

/// Token 模式失败回调
/// @param error 失败信息,包含 sdkToken、errorCode 和 errorMsg
typedef void (^OcrCloudFailedBlock)(OcrCloudError *_Nonnull error);
说明:
成功回调触发后,SDK 仅返回 sdkToken,最终识别结果需由宿主 App 服务端凭 sdkToken 向腾讯云 OCR 拉取。
用户主动取消识别会触发失败回调,errorCode 为 200101。
API 接口返回可参考 官网文档,错误码说明可参考 错误码。


帮助和支持

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

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

文档反馈