standard

全球版图像质量检测服务 SDK 集成文档

集成 SDK 到您的工程中

在您项目根目录下的build.gradle增加 maven 仓库依赖


xxxxxxxxxx
allprojects {
    repositories {
        google()
        jcenter()
        ...
        maven {
            url 'https://public-n3.advai.net/repository/maven-releases/'
        }
    }
}

在app/build.gradle中增加增加包依赖


xxxxxxxxxx
dependencies {
   ...
  // 版本记录查看：http://public-n3.advai.net/repository/maven-releases/ai/advance/mobile-sdk/android/global-iqa/maven-metadata.xml
  implementation 'ai.advance.mobile-sdk.android:global-iqa:1.2.8' 
}

SDK 版本更新

您可以通过以下链接查看版本记录

快速入门

初始化 SDK

在自定义的 application 中增加如下初始化代码


xxxxxxxxxx
GlobalIQASDK.init(application);

设置 license (由您的服务端调用 openAPI 获取 license)


xxxxxxxxxx
String checkResult = GlobalIQASDK.setLicenseAndCheck(license);
if ("SUCCESS".equals(checkResult)) {
    // license 有效
   startGlobalIQAActivity();
} else {
    // license 不可用，过期/格式错误/appId不在授权列表内
}

用户绑定(强烈建议)。
您可以通过该方法将自己的用户唯一标识传给我们，我们会根据该标识建立映射关系。当遇到问题时，方便同我们进行日志追踪。
```
xxxxxxxxxx
GlobalIQASDK.bindUser(String userId)    
```

启动与获取结果

我们提供了两种方式来获取图片和检测结果，您可以通过 SDK 直接获取，也可以在后端通过 IDVID 请求结果。

支持通过如下示例代码修改页面的风格，如果下方的样式无法满足您的自定义需求，请点击此处下载UI源码进行您的自定义操作


xxxxxxxxxx
/**
 * 请求状态码
 */
public static final int REQUEST_CODE_IQA = xxxx;

/**
 *  启动页面
 * @param region 地区 ISO 码，使用2位或者3位简码都可以，参见维基百科：https://zh.wikipedia.org/wiki/ISO_3166-1
 * @param cardType 卡片类型，枚举值： ID_CARD，DRIVING_LICENSE，UMID，SSS，TIN，PASSPORT，VOTERID，NATIONALID，PRC，PAGIBG，POSTALID
 * @param cardSide 卡片正反面，枚举值： FRONT，BACK
 */
private void startGlobalIQAActivity(String region, CardType cardType, CardSide cardSide) {
    Intent intent = new Intent(MainActivity.this, GlobalIQAActivity.class);
    intent.putExtra(GlobalIQAActivity.EXTRA_IQA_EXTRAS,
            new IQAExtras.Builder(region, cardType, cardSide)
                    .setSoundPlayEnable(true) // 声音播报是否开启，默认开启
                    .setReturnEmptyOfOCR(false)//是否在识别为空的字段上返回null，默认为false
                    .setMode(Mode.DEFAULT)// 设置启动模式：扫描/拍照/默认
                    .build());
    // UI 色调自定义，非必须                
    UIExtras.Builder builder = new UIExtras.Builder()
                    .setPageColor(getResources().getColor(R.color.cardview_dark_background))// 页面主色调
                    .setPrimaryTextColor(your colorRes) // 页面主体文字颜色
                    .setFrameRectColor(your colorRes) // 相机蒙版层的颜色
                    .setFrameRectCornerRadius(20) // 相机控件蒙版支持设置圆角（单位：px）
                    .setTitleBackGroundColor(your colorRes) // 标题栏的颜色
                    .setFlipCameraBtnVisible(false)// 切换相机按钮是否可见，默认可见
                    .setLightBtnVisible(false)// 手电筒按钮是否可见，默认可见
                    .setTipIconVisible(false)// 竖屏扫描过程中底部提示控件的小图标是否可见
                    .setTitleTextColor(your colorRes)// 标题栏文字颜色
                    .setPagePortraitBackgroundResource(R.drawable.xxx)//竖屏状态下页面的背景图片
                    .setPageLandscapeBackgroundResource(R.drawable.xxx)//横屏状态下页面的背景图片
                    .setPageLandscapeTitleBgResource(R.drawable.xxx)//横屏状态下页面标题部分背景图片
                    .setPagePortraitTitleBgResource(R.drawable.xxx)//竖屏状态下页面标题部分背景图片
                    .setCameraWidthPercentInPortraitState(0.8f)// 竖屏状态相机控件占屏幕的百分比，取值0～1
                    .setCameraHeightPercentInLandscapeState(0.7)// 竖屏状态相机控件占屏幕的百分比，取值0～0.7
                    .setRetakeBtnTextColor(your colorRes)//拍照模式重拍按钮文字颜色
                    .setContinueBtnTextColor(your colorRes)//拍照模式继续按钮文字颜色
                    .setTakePhotoTipDialogShowSeconds(3)//扫描超时提示框倒计时秒数设置，设置为0则不会弹框
                    .setScanLimitSeconds(20)// 扫描超时时间设置，单位秒，取值5～60
                    .setCountdownTimerVisible(true)// 扫描模式是否显示倒计时控件，默认显示(此设置不会影响倒计时逻辑，仅决定控件是否显示)
                    .setTakePhotoViewIcon(R.drawable.xxx)// 拍照按钮图标
                    .setTakePhotoTipViewBackgroundColor(your colorRes)// 拍照模式，相机控件下方提示语控件的背景色
                    .takePhotoTipViewLeftIconVisible(false)// 拍照模式，相机控件下方提示语控件左侧的图标是否可见，默认可见
                    .setScreenOrientation(ScreenOrientation.xx);// 锁定屏幕方向，默认自适应旋转方向，枚举值：LANDSCAPE，PORTRAIT，AUTO
                    
  // 通过下面的方法，可以设置扫描时相机控件下方提示语的 UI 样式
  TipViewUIElements elements = new TipViewUIElements();
  elements.setNoCardDrawableResId(R.drawable.xxx);// 未检测到卡片
  elements.setHoldSteadilyDrawableResId(R.drawable.xxx);// 请扶稳手机
  elements.setCardPoorQualityDrawableResId(R.drawable.xxx);// 卡片质量差：模糊/光斑/过暗
  elements.setCardIncompleteDrawableResId(R.drawable.xxx);// 卡片不完整
  elements.setCardTooSmallDrawableResId(R.drawable.xxx);// 卡片过小
  elements.setCardOccludedDrawableResId(R.drawable.xxx);// 卡片被遮挡
  elements.setViewWidthPercentRelativeToCameraView(1f); // 提示语控件相对于相机控件的宽度比例，如：设置为1表示何相机控件等宽
  elements.setAspectRatio(0.25f);// 控件宽高比，宽/高
  builder
  .setPortraitTipViewBackgrounds(elements)// 竖屏
  .setLandscapeTipViewBackgrounds(landscapeElements)// 横屏
  intent.putExtra(GlobalIQAActivity.EXTRA_UI_EXTRAS,builder.build());
  
  // 相机控件上方文字支持传入富文本:
  SpannableString spannableString1 = new SpannableString("xxxxx");
  spannableString1.setSpan(....);
  intent.putExtra(GlobalIQAActivity.EXTRA_SPANNABLE_ABOVE_CAMERA, spannableString1);
  // 拍照模式，相机控件下方提示语支持传入富文本:
  SpannableString spannableString2 = new SpannableString("xxxxx");
  spannableString2.setSpan(....);
  intent.putExtra(GlobalIQAActivity.EXTRA_SPANNABLE_TIP_TEXT_OF_TAKE_PHOTO, spannableString2);
  // 拍照模式，拍照后预览时图像下方提示语支持传入富文本:
  SpannableString spannableString3 = new SpannableString("xxxxx");
  spannableString3.setSpan(....);
  intent.putExtra(GlobalIQAActivity.EXTRA_SPANNABLE_PREVIEW_TIP_OF_TAKE_PHOTO, spannableString3);
    startActivityForResult(intent, REQUEST_CODE_IQA);
}

@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    if (requestCode == REQUEST_CODE_IQA) {
        boolean success = GlobalIQAResult.isSuccess();
        if (success) {
            String idvid = GlobalIQAResult.getIDVID();// 图像 id
            Bitmap bitmap = GlobalIQAResult.getBitmap();// bitmap 格式的图像
            String pictureType = GlobalIQAResult.getPictureType();// 图片类型，takePhoto 表示拍照，scan 表示扫描
            String base64Image = GlobalIQAResult.getBase64Image();// base64格式的图像
            JSONObject idForgeryResult = GlobalIQAResult.getIdForgeryResult();//假证结果
            JSONObject ocrResult = GlobalIQAResult.getOCRResult();// ocr 结果
            String transactionId = GlobalIQAResult.getTransactionId();// 本次的事务id
            boolean pay = GlobalIQAResult.isPay();//本次调用是否计费
        } else {
            String errorCode = GlobalIQAResult.getErrorCode();// 本次错误码
            String errorMsg = GlobalIQAResult.getErrorMsg();//本次错误描述信息，可能为空
            String transactionId = GlobalIQAResult.getTransactionId();//本次的事务id，可能为空
        }
    }
}

ErrorCode	解释
USER_GIVE_UP	用户点击了返回键
DEVICE_NOT_SUPPORT	SDK不支持该手机
PARAMETER_ERROR	参数错误
OCR_NO_RESULT	OCR识别结果为空
TOO_MANY_CARDS	OCR识别结果检测到多张卡片
其它通用Code	参见文档

图片元素自定义

利用 gradle 打包合并资源的机制，在您的app模块中放置 SDK 中的同名图片资源，从而实现图片元素的自定义。

各个图片资源的名称对应关系如下：


xxxxxxxxxx
iqa_back 返回按钮
iqa_land_confirm 横屏确认按钮
iqa_land_retake 横屏重拍按钮
iqa_light_off 手电筒关闭按钮
iqa_light_on 手电筒打开按钮
iqa_scan_processing 横屏扫描时底部实时提示的 icon，对应文案为：请扶稳手机
iqa_scan_successfully 横屏扫描时底部实时提示的 icon，对应文案为：证件扫描成功
iqa_scan_warning 横屏扫描时底部实时提示的 icon，对应提示卡片问题(模糊，卡片不全，面积小等)
iqa_take_photo 拍照按钮
iqa_take_photo_tip 拍照模式时，相机下方提示的文案左侧小 icon
iqa_transform_camera 切换摄像头普通状态
iqa_transform_camera_pressed 切换摄像头按压状态
advance_iqa_tip_capture 扫描超时后，弹出倒计时框里的icon
advance_iqa_scan 扫描时，相机上的扫描动画图片

文字自定义

利用 gradle 打包合并资源的机制，在您的app模块中放置 SDK 中的同名文字资源，从而实现文字元素的自定义。


xxxxxxxxxx
// 文字资源英文名称 & 内容列表，替换时请注意语言国际化
<resources>
    <string name="no_card">No document is detected</string>
    <string name="hold_phone">Please hold the phone steadily</string>
    <string name="iqa_no_camera_permission">Camera is not turned on, please turn on camera permissions</string>
    <string name="iqa_confirm">Yes</string>
    <string name="iqa_auth_check">Please Wait</string>
    <string name="iqa_failed_reason_bad_network">Please check network</string>
    <string name="too_small_card">Document is too small</string>
    <string name="device_not_support">The device does not supported</string>

    <string name="iqa_time_out_tips">Time out, try taking photo manually.</string>
    <string name="iqa_retry_tips">Time out, please try again.</string>

    <string name="iqa_scan_document">Scan Document</string>
    <string name="iqa_front_side_of_document">Front Side of Document</string>
    <string name="iqa_back_side_of_document">Back Side of Document</string>
    <string name="iqa_top_desc">Please place the document in the center with the edges aligned</string>
    <string name="iqa_card_poor_quality">Document is too dim/blurred/overexposed</string>
    <string name="iqa_scan_successfully">Document collected successfully</string>
    <string name="iqa_min_gap_ratio">The document is incomplete\nplease make sure the document in the center with the edges aligned</string>
    <string name="iqa_take_photo_tips">Try taking photo manually\nAlign document, then press button</string>
    <string name="iqa_take_photo_ensure">Please ensure that all data on your documents is visible and readable.</string>
    <string name="iqa_retake">Retake</string>
    <string name="iqa_continue">Continue</string>
  <string name="iqa_card_occluded">Please keep your ID card unobstructed</string>
</resources>

国际化
SDK 支持英文，印尼语，中文三种语言/语音，跟随手机系统语言自动切换。
- 若没有跟随系统语言自动切换，请检查手机语言设置，确保【地区】和【语言】均已切换至对应的语言
- 若仍然出现语言国际化问题，同时 app 仅支持某种语言，可以通过在build.gradle中增加如下配置，过滤掉不需要的语言
```
xxxxxxxxxx
android {
  defaultConfig {
    ...
    resConfigs("in-rID") // 以仅支持印尼语为例
  }

}
```

运行时权限

本 SDK 需要如下权限，并且已经在 aar 的清单文件中做了配置且 SDK 本身已经做好了安卓 6.0 以上权限的动态申请。


xxxxxxxxxx
<uses-feature android:name="android.hardware.camera" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />

关于 App Bundle 打包
SDK 中包含 .so 文件，为了减少包大小，在上架 Google Play 时可以选择使用 Bundle 打包，请验证打包后的 APK 在各个架构的手机上都可以运行，如果出现提示【该设备不支持】，则表示组装 APK 时缺失了 .aar 中的 .so 文件，请联系我们索取 .so 与 .aar 分离的版本。
代码混淆
SDK 已经做好了代码混淆，无需额外增加配置。
关于Androidx
考虑到 Androidx 与 support 包的互斥，本 SDK 的 .aar 全部是 support 包，如果您的项目是 androidX 类包，编译时遇到提示 support 包冲突错误，请在您项目的根目录下的gradle.properties文件中增加下述配置，重新编译项目即可：
```
xxxxxxxxxx
android.enableJetifier=true 
```
SDK 兼容性
- 最低 Android 版本：4.4 (API Level:19)
- SDK 编译版本：API Level：34
- 额外依赖的第三方库：无
- 支持的 CPU 架构：armeabi-v7a，arm64-v8a，x86，x86_64，armeabi
- SDK 包大小：0.9MB 模型文件 + 每种 CPU 架构约 0.7MB