Global IQA SDK Flutter plugin Integration Guide

Overview

Android

• Minimum Android version：4.4 (API Level:19)

• Compilation Android SDK version：API Level：35

• Supported CPU architectures：armeabi-v7a，arm64-v8a

• Use-permissions:

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

iOS

• Minimum iOS version: iOS 12.0
• Supported CPU architectures: arm64
• SDK incremental package size: ~0.7M
• Use-permissions: NSCameraUsageDescription

If you previously integrated using the source code method, please switch to dependency integration and refer to the migration document.

pub.dev dependency

1. Add pub spec.yaml dependency

   xxxxxxxxxx
   dependencies:
     iqc_plugin: ^1.5.3 
   

2. For the Android platform,set the largeHeap property to true (strongly recommended)

   xxxxxxxxxx
   <application android:largeHeap="true" />
   

3. For the iOS platform,the following configurations need to be added:

   1. Add camera usage description in Info.plistas below. Ignore this step if you have added those

      xxxxxxxxxx
      <key>NSCameraUsageDescription</key>  
      <string>Your description</string>
      

   2. Add the spec source to the podfile file in your project

      xxxxxxxxxx
      source 'https://github.com/advance-ai-mobile/aai-specs.git'
      source 'https://cdn.cocoapods.org/'
      

3. Run pod install --repo-update

Quick Start

1. Declare the plugin.

   xxxxxxxxxx
   import 'package:iqc_plugin/iqc_plugin.dart';
   

2. Initialize the SDK.

   xxxxxxxxxx
   void main() {
     WidgetsFlutterBinding.ensureInitialized();
     GlobalIQCPlugin.initialize();
     runApp(MyApp());
   }
   

3. Get the SDK version number.

   xxxxxxxxxx
   GlobalIQCPlugin.getSDKVersion.then((sdkVersion) {
       print(sdkVersion);
   });
   

4. Check license

   The license is obtained by your server calling our openAPI, you need to check license before starting the IQA activity.

   ​x
   String license = "xxx";
   GlobalIQCPlugin.initSDK();
   String? result = await GlobalIQCPlugin.setLicenseAndCheck(license);
   
   print("result = " + result.toString());
   if ("SUCCESS" == result) {
     startGlobalIQCDetection();
   }
   
   The returned values of checkResult:
   
   APPLICATION_ID_NOT_MATCH: The package name is not within the authorized scope, please check your package name.
   
   LICENSE_EXPIRE: The license has expired, please confirm that the user has calibrated the phone time.
   
   ERROR_LICENSE(1): The license parsing succeeded, but necessary authentication information is missing, this case generally will not occur.
   
   ERROR_LICENSE(2): The license parsing succeeded, but the internal format is incorrect, this case also generally will not occur.
   
   ERROR_LICENSE(3): It is highly likely that an incompatible SDK license is being used, such as using an IQA license for liveness detection.
   
   ERROR_LICENSE(4, 5): Parsing failed, please check if the license has issues like mismatched quotes, line breaks, etc.
   

5. 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
   GlobalIQCPlugin.bindUser("UserId");  
   

6. 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.

   xxxxxxxxxx
   Map<String, dynamic> localizedStrs = {"th.no_card": "your text"};
   
   void startGlobalIQCDetection() {
     GlobalIQCPlugin.startGlobalIQC(this, {
       "region": "ID",
       "cardType": "ID_CARD",
       "cardSide": "FRONT",
       "mode": "DEFAULT",
       "pageColor": "#ffffff",
       "primaryTextColor": "#000000",
       "frameRectColor": "#00ffff",
       "frameRectCornerRadius": 20,
       "titleBackgroundColor": "#00ff00",
       "flipCameraBtnVisible": true,
       "lightBtnVisible": true,
       "tipIconVisible": true,
       "titleTextColor": "#0000ff",
       "cameraWidthPercentInPortraitState": 0.8,
       "cameraHeightPercentInLandscapeState": 0.7,
       "retakeBtnTextColor": "#ff00ff",
       "continueBtnTextColor": "#00ff00",
       "takePhotoTipDialogShowSeconds": 5,
       "scanLimitSeconds": 30,
       "countdownTimerVisible": true,
       "takePhotoTipViewLeftIconVisible": true,
       "takePhotoTipViewBackgroundColor": "#ffffff",
       "screenOrientation": "PORTRAIT",
       "portraitTipConfig":
       "{\"viewWidthPercentRelativeToCameraView\": 1, \"aspectRatio\": 0.3}",
       "landscapeTipConfig":
       "{\"viewWidthPercentRelativeToCameraView\": 0.3, \"aspectRatio\": 0.1}",
       "localizedStrs": localizedStrs, //It only takes effect on iOS
       "fontName":"MapleMono-Light", //It only takes effect on iOS
       "language": "en" //It only takes effect on iOS
     });
   }
   
   @override
   void onGetGlobalIQCResult(bool isSuccess, Map<dynamic, dynamic>? resultMap) {
     print("IQCPlugin onGetDetectionResult isSuccess:" + isSuccess.toString());
     print("IQCPlugin onGetDetectionResult print result:" + resultMap.toString());
   }
   

Advanced iOS Customization

1. Setting the Interface Language

You can set the SDK's display language by passing a language parameter. If this parameter is omitted, the SDK will default to the current system language.

xxxxxxxxxx
// Add the language parameter in the GlobalIQCPlugin.startGlobalIQC method.
GlobalIQCPlugin.startGlobalIQC({
  // ... other parameters
  "language": "en" 
});

Supported Language Codes:

• "en": English
• "id": Indonesian
• "zh-Hans": Simplified Chinese
• "th": Thai

2. Overriding Specific Text Strings

The SDK allows you to override any default text string for any supported language. This is useful for customizing specific labels, messages, or buttons to better match your app's tone.

Steps:

1. Find the Text Key: All available keys can be found in the following file within your Xcode project:

   xxxxxxxxxx
   ios/Pods/Resources/AAIGlobalIQAUI/AAIIQALanguageString.bundle/en.lproj/Localizable.strings
   

2. Construct the Override Map: Create a Map<String, dynamic> where each key is a composite string in the format {language_code}.{text_key} and the value is your custom text.

3. Pass the Parameter: Add this map to the startGlobalIQC method using the localizedStrs parameter.

Example:

xxxxxxxxxx
// 1. Define your custom strings map.
Map<String, dynamic> customStrings = {
  "th.no_card": "ข้อความภาษาไทยที่กำหนดเอง", // Your custom Thai text
  "en.no_card": "Your Custom English Text" // Your custom English text
};

// 2. Pass it to the startGlobalIQC method.
GlobalIQCPlugin.startGlobalIQC({
  // ... other parameters
  "localizedStrs": customStrings
});

3. Using a Custom Font

You can apply a custom font to all text within the SDK to maintain a consistent brand identity.

Steps:

1. Add Font File to Your Xcode Project:

   • Drag and drop your custom font file (e.g., MyCustomFont.ttf) into your main iOS project in Xcode.
   • In the "Add to targets" dialog, ensure your main app target is selected.

2. Register the Font in Info.plist:

   • Open your project's Info.plist file.
   • Add a new key named Fonts provided by application (raw key: UIAppFonts).
   • This key should be an array. Add a new string item to this array with the full name of your font file.

   xxxxxxxxxx
   <key>UIAppFonts</key>
   <array>
       <string>MyCustomFont.ttf</string>
   </array>
   

3. Pass the Font Name Parameter:

   • Add the fontName parameter to the startGlobalIQC method. The value should be the PostScript name of the font (which may differ from the file name).

   xxxxxxxxxx
   // The PostScript name for "MyCustomFont.ttf" might be "MyCustomFont-Regular"
   GlobalIQCPlugin.startGlobalIQC({
     // ... other parameters
     "fontName": "MyCustomFont-Regular" 
   });
   

   Note: To find the correct PostScript name, open the font file on your Mac with the "Font Book" application and check its info panel.

4. Overriding Default Images

The SDK allows you to replace its default icons and images with your own custom assets.

Steps:

1. Find the Image Name: All default image names can be found by browsing the asset catalog located at:

   xxxxxxxxxx
   ios/Pods/Resources/AAIGlobalIQAUI/AAIIQAImgs.xcassets/
   

2. Prepare Your Custom Image:

   • Your custom image file must be named with an aai_ prefix. For example, if you want to replace the default iqa_scan_successfully image, your new file should be named aai_iqa_scan_successfully.
   • This naming convention prevents conflicts with your app's other assets.

3. Add Image to Your Project's Assets:

   • Drag and drop your custom image (e.g., aai_iqa_scan_successfully.png) into your main app's primary asset catalog (Assets.xcassets).

How it Works:

The SDK will automatically detect your custom images. For any given image, it first looks for an asset with the aai_{imageName} naming convention in your main project's asset catalog.

• If a match is found, your custom image is used.
• If no match is found, the SDK's default image is used as a fallback.
• No Dart code is needed for this customization; it is handled automatically based on the presence of the correctly named image assets.

Advanced Android Customization

1. Specifying a Single Language

If your app only supports one language and does not require multi-language support, you can add the following configuration in your_flutter_project/android/app/build.gradle:

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

Since the default language of the SDK is English, meaning the values directory contains English resources, you need to copy the language resources from the values-in-rID folder to the values directory to replace the English resources.

2. Overriding Specific Text Strings

You can customize the SDK's text strings by adding or modifying the strings.xml file in the corresponding language resource directory under your_flutter_project/android/app/src/main/res/. The SDK supports the following languages:

For example, to customize English strings, edit your_flutter_project/android/app/src/main/res/values/strings.xml. To customize Indonesian strings, edit your_flutter_project/android/app/src/main/res/values-in-rID/strings.xml, and so on for other languages.

Change the value to whatever text you want to display. Below is the full list of customizable string keys (shown with English defaults):

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>
    <string name="iqa_card_too_glossy">Document has reflections, please retry by adjusting the angle</string>
</resources>

3. Using a Custom Font

Place your custom font file (e.g., my_font.ttf, the file name can be anything) in the your_flutter_project/android/app/src/main/res/font directory. Then add the following theme configuration in your_flutter_project/android/app/src/main/res/values/themes.xml:

xxxxxxxxxx
<style name="Theme.IqaSdk" parent="Theme.IqaSdk.Base">
    <item name="aaiIqaFontFamily">@font/my_font</item>
</style>

This will change the font of the IQA pages to the font you specified.

4. Overriding Default Images and Backgrounds

You can replace the SDK's default images and backgrounds by adding files with the same name to the your_flutter_project/android/app/src/main/res/drawable directory. The following files can be overridden:

• global_iqa_ripple_gray.xml
• iqa_back.xml
• iqa_bg_continue.xml
• iqa_bg_retake.xml
• iqa_bg_tips.xml
• iqa_countdown_bg.xml
• iqa_icon_info_normal.xml
• iqa_land_black_tips.xml
• iqa_land_confirm.xml
• iqa_land_green_tips.xml
• iqa_land_red_tips.xml
• iqa_land_retake.xml
• iqa_light_off.xml
• iqa_light_on.xml
• iqa_scan_processing.xml
• iqa_scan_successfully.xml
• iqa_scan_warning.xml
• iqa_take_photo_tip.xml
• iqa_take_photo.xml
• iqa_timeout_tips_bg.xml
• iqa_transform_camera_pressed.xml
• iqa_transform_camera.xml
• selector_transform_camera.xml