standard

SDK Integration Documentation

Integrate the SDK into your project

Add a maven repository dependency to build.gradle in the root of your project


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

Adding package dependencies to app/build.gradle


xxxxxxxxxx
dependencies {
   ...
  // Version Release History：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 Version update

You can view the version log at the following link

Quick Start

Initialize the SDK

Add the following initialization code to the custom application


xxxxxxxxxx
GlobalIQASDK.init(application);

Set the license (your server calls openAPI to get the license)


xxxxxxxxxx
String checkResult = GlobalIQASDK.setLicenseAndCheck(license);
if ("SUCCESS".equals(checkResult)) {
    // license enabled
   startGlobalIQAActivity();
} else {
    // license is not available, expired/wrong format/appId is not in the license list
}

User binding (highly recommended).
You can use this method to pass us your unique user ID, and we will establish a mapping relationship based on that ID. It's easy to track logs with us in case of problems.
```
xxxxxxxxxx
GlobalIQASDK.bindUser(String userId)    
```
Start and Get Results

We provide two ways to get images and detection results, you can get them directly through the SDK or you can request the results via IDVID.

Supports modifying the page style through the example code below. If the styles provided do not meet your customization needs, please click here to download the UI source code for your custom modifications.


xxxxxxxxxx
/**
 * The request code
 */
public static final int REQUEST_CODE_IQA = xxxx;

/**
 *  Start
 * @param region Regional ISO codes, use either 2 or 3 digit short codes, see Wikipedia: https://en.wikipedia.org/wiki/ISO_3166-1
 * @param cardType Card type, enumeration value:ID_CARD,DRIVING_LICENSE,UMID,SSS,TIN,PASSPORT,VOTERID,NATIONALID,PRC,PAGIBG,POSTALID
 * @param cardSide Card front and back, enumerated values: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) // Whether the sound broadcast is on, the default is on
                    .setReturnEmptyOfOCR(false)//Whether to return null on fields identified as empty, default is false
                    .setMode(Mode.DEFAULT)// The start mode:SCAN/TAKE_PHOTO/DEFAULT
                    .build());
    // UI color tone customization, not required        
     UIExtras.Builder builder = new UIExtras.Builder()
                 .setPageColor(getResources().getColor(R.color.cardview_dark_background))// Page main color
                 .setPrimaryTextColor(your colorRes) // Page main text color
                 .setFrameRectColor(your colorRes) // The color of the camera mask layer
                 .setFrameRectCornerRadius(20) // Rounded corners of camera mask layer (in px)
                 .setTitleBackGroundColor(your colorRes) // Color of the title bar
                 .setFlipCameraBtnVisible(false)// Whether the flip camera button is visible,default is true
                 .setLightBtnVisible(false)// Whether the flashlight button is visible, the default is visible
                 .setTipIconVisible(false)// Whether the small icon of the bottom prompt control is visible during vertical scanning
                 .setTitleTextColor(your colorRes)// The text color of title bar
                 .setPagePortraitBackgroundResource(R.drawable.xxx)// The page background picture at portrait state
                 .setPageLandscapeBackgroundResource(R.drawable.xxx)// The page background picture at landscape state
                 .setPageLandscapeTitleBgResource(R.drawable.xxx)// The title background picture at portrait state
                 .setPagePortraitTitleBgResource(R.drawable.xxx)// The page background picture at landscape state
                 .setCameraWidthPercentInPortraitState(0.8f)// The width percent of camera view when the page at  portrait state,the value must between [0,1]
                 .setCameraHeightPercentInLandscapeState(0.7)// The width percent of camera view when the page at landscape state,the value must between [0,0.7]
                 .setRetakeBtnTextColor(your colorRes)//The retake button text color in 'Take Photo' mode
                 .setContinueBtnTextColor(your colorRes)// The continue button text color in 'Take Photo' mode
                 .setTakePhotoTipDialogShowSeconds(3)// The tip dialog(when scanning timeout) duration seconds, set to 0 will not show the dialog
                 .setScanLimitSeconds(20)// The scanning seconds limit,the value must between [5,60]
                 .setCountdownTimerVisible(true)// Whether the countdown timer view shown
                 .setTakePhotoViewIcon(R.drawable.xxx)// Take photo button icon
                 .setTakePhotoTipViewBackgroundColor(your colorRes) // The background color of the tip view in take photo mode
                 .takePhotoTipViewLeftIconVisible(false) // The left icon of the tip view below the camera view in take photo mode
                 .setScreenOrientation(ScreenOrientation.xx);// Lock screen orientation, default adaptive rotation direction, enumerated values: LANDSCAPE, PORTRAIT, AUTO
            
  // In scan mode, you can customize the style of the tip view：
  TipViewUIElements elements = new TipViewUIElements();
  elements.setNoCardDrawableResId(R.drawable.xxx);// No card detected
  elements.setHoldSteadilyDrawableResId(R.drawable.xxx);// Please hold the phone steady
  elements.setCardPoorQualityDrawableResId(R.drawable.xxx);// Card poor quality: blurred/spotty/too dark
  elements.setCardIncompleteDrawableResId(R.drawable.xxx);// Card incomplete
  elements.setCardTooSmallDrawableResId(R.drawable.xxx);// Card too small
  elements.setCardOccludedDrawableResId(R.drawable.xxx);// Card occluded
  elements.setViewWidthPercentRelativeToCameraView(1f); // The width of the tip view relative to the camera view, e.g., set to 1 for equal width of the camera view
  elements.setAspectRatio(0.25f);// Tip view aspect ratio,width/height
  builder
  .setPortraitTipViewBackgrounds(elements)// In portrait
  .setLandscapeTipViewBackgrounds(landscapeElements)// In landscape
  intent.putExtra(GlobalIQAActivity.EXTRA_UI_EXTRAS,builder.build());
  
  // The text above the camera view supports passing in rich text:
  SpannableString spannableString1 = new SpannableString("xxxxx");
  spannableString1.setSpan(....);
  intent.putExtra(GlobalIQAActivity.EXTRA_SPANNABLE_ABOVE_CAMERA, spannableString1);
  // In take photo mode,support for setting rich text to the tip view below the camera view:
  SpannableString spannableString2 = new SpannableString("xxxxx");
  spannableString2.setSpan(....);
  intent.putExtra(GlobalIQAActivity.EXTRA_SPANNABLE_TIP_TEXT_OF_TAKE_PHOTO, spannableString2);
  // In take photo mode,support for setting rich text for the tip view below the image when previewing after taking a photo:
  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();// image id
            Bitmap bitmap = GlobalIQAResult.getBitmap();// Image in bitmap format
            String pictureType = GlobalIQAResult.getPictureType();// Picture type,"takePhoto" or "scan"
            String base64Image = GlobalIQAResult.getBase64Image();// Image in base64 format
            JSONObject idForgeryResult = GlobalIQAResult.getIdForgeryResult();// ID forgery result
            JSONObject ocrResult = GlobalIQAResult.getOCRResult();// ocr result
            String transactionId = GlobalIQAResult.getTransactionId();// transaction id
            boolean pay = GlobalIQAResult.isPay();// Whether this call is billed or not
        } else {
            String errorCode = GlobalIQAResult.getErrorCode();// error code
            String errorMsg = GlobalIQAResult.getErrorMsg();//error message,may be null
            String transactionId = GlobalIQAResult.getTransactionId();//transaction id,may be null
        }
    }
}

Image element customization

Use the gradle package merge resource mechanism to place image resources of the same name from the SDK in your app module to customize the image elements.

The names of the individual image resources correspond as follows:


xxxxxxxxxx
`iqa_back` Back button icon on the title bar
`iqa_land_confirm` Landscape confirmation button icon
`iqa_land_retake` Landscape reshoot button icon
`iqa_light_off` Flashlight off icon
`iqa_light_on` Flashlight on icon
`iqa_scan_processing` The icon at the bottom of the screen when scanning in landscape
`iqa_scan_successfully` Real-time icon at the bottom of the screen when scanning
`iqa_scan_warning` Real-time icon at the bottom of the screen when scanning in landscape
`iqa_take_photo` Take photo button icon
`iqa_take_photo_tip` When taking pictures, the small icon to the left of the text prompted at the bottom of the camera
`iqa_transform_camera`Switching camera normal status
`iqa_transform_camera_pressed` Switching camera pressed status
`advance_iqa_tip_capture` After the scan timeout, the icon in the countdown box pops up
`advance_iqa_scan` Scanning animation picture on the camera while scanning

Text customization

Use the gradle package merge resource mechanism to place text resources of the same name from the SDK in your app module to enable customization of image elements.


xxxxxxxxxx
// String resources name & content list of en, please note the language internationalization when replacing
<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>

Multilingual
SDK supports three languages, English, Indonesian and Chinese, switching automatically with the cellphone system language.
- If the SDK does not automatically switch with the system language, please check your cellphone language settings and make sure that both [Region] and [Language] are switched to the corresponding language.

If it still have problems with multiple languages and the app only supports one language, you can filter out the unwanted languages by adding the following configuration to build.gradle


xxxxxxxxxx
android {
  defaultConfig {
    ...
    resConfigs("in-rID") // For example, only Indonesian is supported
  }
  
}

Runtime Permissions

This SDK requires the following permissions, which have been configured in the aar manifest file and the SDK itself is ready for dynamic application of Android 6.0+ permissions.


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

About App Bundle Bundling
Please verify that the packaged APK will work on all architectures of cell phones. If you are prompted with [this device is not supported], it means that the .so file in .aar is missing when assembling the APK. Please contact us for a separate version of .so and .aar.
Code proguard configuration
The SDK already has code proguard, no additional configuration is required.
About androidx
Considering the mutually exclusive nature of AndroidX and android.support.* packages, all the .aar of this SDK are android.support.* packages. If your project is an AndroidX package and you encounter a android.support.* package conflict error when compiling, please add the following configuration to the gradle.properties file in the root directory of your project and recompile the project and you will be able to：
```
xxxxxxxxxx
android.enableJetifier=true 
```
SDK Compatibility
- Minimum Android version：4.4 (API Level:19)
- Compilation Android SDK version：API Level：34
- Additional dependent third-party libraries: None
- Supported CPU architectures：armeabi-v7a,arm64-v8a,x86,x86_64,armeabi
- SDK package size: 0.9MB model file + about 0.7MB per CPU architecture