Migration Guides (Cordova)

Migration Overview

The migration process consists of four main steps:

1. Remove Old Integration Files: Clean up all manually integrated native code and resource files for both Android and iOS.
2. Install the New Cordova Plugin: Add the new plugin to your project using npm.
3. Update Native Project Configurations: Ensure permissions and other settings in your native projects are correctly configured.
4. Update JavaScript API Calls: Replace the old JavaScript code with the new API to initialize the SDK and invoke its features.

Step 1: Remove the Old Integration

Before integrating the new plugin, you must completely remove the old SDK files to prevent conflicts.

Android

1. Remove AAR/JAR Files: Navigate to your Android project's libs directory (usually at platforms/android/app/libs) and delete all .aar or .jar files related to the Advance.ai SDK.
2. Clean build.gradle: Open your app-level build.gradle file and remove any dependency references to the local library files you just deleted.
3. Remove Native Code: If you wrote any custom native Java or Kotlin code (e.g., a custom Cordova plugin wrapper) to interact with the SDK, delete these files.
4. Clean AndroidManifest.xml: Temporarily remove any <uses-permission> and <uses-feature> tags you previously added for the SDK. These will be re-added and verified in a later step.

iOS

1. Remove Frameworks: In Xcode, locate the "Frameworks, Libraries, and Embedded Content" section under your target's "General" tab. Remove any .framework or .xcframework files associated with the Advance.ai SDK. Also, delete these files from your project directory.
2. Clean Project Settings: Review your "Build Settings" and "Build Phases" for any custom configurations or scripts related to the old SDK and remove them.
3. Remove Native Code: Delete any Objective-C or Swift bridge files you created to communicate with the SDK.

Step 2: Install the New Plugin via npm

With the old integration removed, you can now add the new plugin using the command line.

1. Open a terminal or command prompt in the root directory of your Cordova project.

2. Run the following command to add the iqa-plugin-cordova:

   cordova plugin add [email protected]
   

   Alternatively, you can add the plugin to your config.xml file and run cordova prepare:

   <plugin name="iqa-plugin-cordova" spec="1.4.2" />
   

3. Verify Installation: Check your plugins/ directory and package.json file to confirm that iqa-plugin-cordova has been successfully added to your project.

Step 3: Update Native Project Configurations

The new plugin handles most configurations automatically, but you should verify that your project meets the minimum requirements.

Android (platforms/android)

1. Check Compile Version: Ensure your project's compileSdkVersion is set to 35 or higher in your app's build.gradle file.

2. Confirm Permissions: The plugin should automatically add the required permissions. Verify that your platforms/android/app/src/main/AndroidManifest.xml contains the following:

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

3. Set largeHeap (Strongly Recommended): To improve performance and stability, add android:largeHeap="true" to the <application> tag in your AndroidManifest.xml:

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

iOS (platforms/ios)

1. Check Minimum Version: Ensure your project's Deployment Target is set to iOS 12.0 or higher.

2. Add Camera Usage Description: The plugin attempts to add this key, but you must verify its presence in your Info.plist file. Provide a clear message to the user explaining why camera access is needed.

   <key>NSCameraUsageDescription</key>
   <string>We need camera access to complete the identity verification process.</string>
   

Step 4: Update JavaScript Code

The new plugin exposes a simpler and more consistent JavaScript API. You will need to replace your existing SDK calls with the new methods.

New Integration Code Example

The following is a complete example demonstrating how to use the new plugin to initialize the SDK, check the license, and start the GlobalIQC flow. You can use this code to directly replace your old logic.

// Get the plugin instance
const iqa = cordova.plugins.iqa;

// Your license key
const iqaLicense = "Your license";

console.log("IQA Step 1: Initializing SDK...");

// 1. Initialize the SDK
iqa.initSDK(() => {
    console.log("IQA SDK initialized successfully.");

    // 2. Set and check the license
    iqa.setLicenseAndCheck(iqaLicense, (result) => {
        // Handle license check failure
        if (result !== 'SUCCESS') {
            // Process the specific error code returned
            // e.g., APPLICATION_ID_NOT_MATCH, LICENSE_EXPIRE, etc.
            console.error(`IQA License Check Failed: ${result}`);
            showMessage(`IQA License Check Failed: ${result}`, 'error');
            return;
        }

        console.log("IQA license check successful. Starting detection...");

        // 3. Prepare parameters and start GlobalIQC
        const iqaParams = {
            // Configure additional parameters here as needed
        };

        iqa.startGlobalIQC(iqaParams, (res) => {
            // Success callback, process the result
            console.log("IQA: Detection Succeeded.", res);
            displayIqaResult(res);
        }, (err) => {
            // Failure callback
            console.error("IQA: Detection Failed.", err);
        });

    }, (err) => {
        console.error("IQA: License Set Failed.", err);
    });

}, (err) => {
    console.error("IQA: SDK Init Failed.", err);
});

// Helper function to display messages in the UI
function showMessage(message, type) {
    // Implement this function based on your UI framework
    alert(`[${type}] ${message}`);
}

// Helper function to process and display the result
function displayIqaResult(result) {
    // Implement this function based on your business logic
    console.log("Processing result:", result);
    alert("Detection complete!");
}

Key Changes

• Plugin Access: The SDK is now accessed globally via cordova.plugins.iqa.
• API Calls: Old methods, often called through a custom exec function, are replaced by direct API calls like iqa.initSDK(), iqa.setLicenseAndCheck(), and iqa.startGlobalIQC().
• Callback Structure: The new API uses a consistent success and error callback pattern, making asynchronous operations cleaner and easier to manage.

Migration Complete

After completing these steps, rebuild your application and run it on both Android and iOS devices to ensure that the integration is working correctly.

If you encounter any issues during the migration, please refer to the latest official documentation or contact our support team.

For detailed integration steps, please refer to the integration document.