How to Upgrade

From v3.4.x to v3.6.x

Update the Libraries

Open the file [App Project Root Path]\app\build.gradle and update the dependency version:

groovy
kts

dependencies {
   implementation 'com.dynamsoft:mrzscannerbundle:{version-number}'
}

dependencies {
   implementation("com.dynamsoft:mrzscannerbundle:{version-number}")
}

Please view user guide for the correct version number.

Click Sync Now. After the synchronization is complete, the updated SDK is added to the project.

Handle Behavior Changes

No public API was removed or renamed in 3.6.x, so an existing integration keeps compiling. Three changes to how the scanner behaves can still affect it.

Results That Fail Check-Digit Validation Are Now Delivered

Through 3.4.x, the scanner discarded any result whose MRZ lines failed check-digit validation and simply carried on scanning. A damaged, misread, or altered document produced no result at all — from the app’s point of view the scan never finished.

3.6.x delivers the result and reports the failure per field instead:

Java
Kotlin

int status = data.getFieldValidationStatus("documentNumber");
if (status == EnumValidationStatus.VS_FAILED) {
   // The value is present but disagrees with its check digit.
}

val status = data.getFieldValidationStatus("documentNumber")
if (status == EnumValidationStatus.VS_FAILED) {
   // The value is present but disagrees with its check digit.
}

Any code that assumed every delivered result was check-digit-clean now has to make that check explicitly. See Reading a field’s validation status in the user guide, and getFieldValidationStatus for the accepted field names.

Camera Access Is Now Gated and Reported

Through 3.4.x, MRZScannerActivity opened the camera regardless of whether the CAMERA permission was held. Without it the preview stayed blank and nothing was reported — the symptom customers described as being stuck on a loading screen.

3.6.x requests the permission on first launch, never opens the camera without it, and reports a denial as RS_EXCEPTION carrying EC_CAMERA_PERMISSION_DENIED (1001) or EC_CAMERA_PERMISSION_RESTRICTED (1002).

Two things to check in existing code:

Handle RS_EXCEPTION. A branch that ignored it will now silently swallow a permission denial that the SDK is reporting properly.
If your app already requests the camera permission itself or presents its own rationale UI, suppress the scanner’s dialog so the user does not see two:

Java
Kotlin

config.setCameraPermissionPromptEnabled(false);

config.isCameraPermissionPromptEnabled = false

The denial is still reported either way. See Handling Camera Permission for the full flow.

Choosing Open Settings in the scanner’s dialog does not finish the activity. Granting the permission in Settings does not kill the Android process either, so the scanner starts the camera in place when the user returns — no result is reported and no restart is needed. This differs from iOS, where changing the setting terminates the app.

The Scan Region Is Now the Guide Frame

Through 3.4.x the whole camera preview was analyzed, so a document held outside the guide frame could still be read. 3.6.x limits capture to the area inside the frame, which is what the frame appeared to promise all along.

If you relied on the wider area — or your users are used to aiming loosely — hiding the guide frame lifts the restriction back to the whole preview. Note that it also hides the prompt text; see Hiding the guide frame.

Adopt the New APIs

These are additive, so adopting them is optional:

getFieldValidationStatus — per-field check-digit status.
EnumErrorCode — the bundle’s own error codes, currently both about camera access.
setCameraPermissionPromptEnabled — suppress the built-in permission dialog.

Your users will also notice two additions to the scanner UI that need no code from you: a progress spinner while MRZ-like text is being processed, and a flip prompt for TD1 and TD2 ID cards whose portrait is on the opposite side. Both are described in The Scanner Screen.

From v3.2.x to v3.4.x

Update the Libraries

Open the file [App Project Root Path]\settings.gradle and add the Maven repository:

groovy
kts

dependencyResolutionManagement {
   repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
   repositories {
      google()
      mavenCentral()
      maven {
         url "https://download2.dynamsoft.com/maven/aar"
      }
   }
}

dependencyResolutionManagement {
   repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
   repositories {
      google()
      mavenCentral()
      maven {
         url = uri("https://download2.dynamsoft.com/maven/aar")
      }
   }
}

If you are using gradle 6.x or older version, the maven dependencies should be configured in [App Project Root Path]\app\build.gradle

Open the file [App Project Root Path]\app\build.gradle and add the dependencies:

groovy
kts

dependencies {
   implementation 'com.dynamsoft:mrzscannerbundle:{version-number}'
}

dependencies {
   implementation("com.dynamsoft:mrzscannerbundle:{version-number}")
}

Please view user guide for the correct version number.

Click Sync Now. After the synchronization is complete, the SDK is added to the project.

Adopt the New Image Capture APIs

v3.4.x adds the ability to retrieve captured images alongside the parsed MRZ data. Three types of images are available via MRZScanResult:

Document image — a cropped, perspective-corrected image of the document. Enabled by default.
Portrait image — the portrait extracted from the document. Enabled by default.
Original image — the raw full-frame camera capture. Disabled by default.

Control which images are returned using the new MRZScannerConfig methods:

Java
Kotlin

MRZScannerConfig config = new MRZScannerConfig();
config.setReturnDocumentImage(true);  // default: true
config.setReturnPortraitImage(true);  // default: true
config.setReturnOriginalImage(false); // default: false — opt in to enable

val config = MRZScannerConfig()
config.setReturnDocumentImage(true)   // default: true
config.setReturnPortraitImage(true)   // default: true
config.setReturnOriginalImage(false)  // default: false — opt in to enable

Retrieve the images from the scan result:

Java
Kotlin

ImageData portrait = result.getPortraitImage();
ImageData docImage = result.getDocumentImage(EnumDocumentSide.DS_MRZ);
ImageData original = result.getOriginalImage(EnumDocumentSide.DS_MRZ);
// For two-sided ID cards, also retrieve the opposite side:
ImageData opposite = result.getDocumentImage(EnumDocumentSide.DS_OPPOSITE);

val portrait = result.getPortraitImage()
val docImage = result.getDocumentImage(EnumDocumentSide.DS_MRZ)
val original = result.getOriginalImage(EnumDocumentSide.DS_MRZ)
// For two-sided ID cards, also retrieve the opposite side:
val opposite = result.getDocumentImage(EnumDocumentSide.DS_OPPOSITE)

All three methods return null if the corresponding return flag is disabled or the image was not captured. getDocumentImage(DS_OPPOSITE) and getOriginalImage(DS_OPPOSITE) also return null for single-sided documents such as passports.

From v2 to v3

Update the Libraries

Open the file [App Project Root Path]\settings.gradle and add the Maven repository:

groovy
kts

dependencyResolutionManagement {
   repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
   repositories {
      google()
      mavenCentral()
      maven {
         url "https://download2.dynamsoft.com/maven/aar"
      }
   }
}

dependencyResolutionManagement {
   repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
   repositories {
      google()
      mavenCentral()
      maven {
         url = uri("https://download2.dynamsoft.com/maven/aar")
      }
   }
}

If you are using gradle 6.x or older version, the maven dependencies should be configured in [App Project Root Path]\app\build.gradle

Open the file [App Project Root Path]\app\build.gradle and add the dependencies:

groovy
kts

dependencies {
   implementation 'com.dynamsoft:mrzscannerbundle:{version-number}'
}

dependencies {
   implementation("com.dynamsoft:mrzscannerbundle:{version-number}")
}

Please view user guide for the correct version number.

Click Sync Now. After the synchronization is complete, the SDK is added to the project.