Cordova SDK 6 Migration Guide

This page covers the Cordova migration from SDK 5.17.x to SDK 6.0.0-beta11.

What changed in SDK 6

• The Cordova plugin now depends on the SDK 6 native minimums: iOS 15 or later and Android API 23 or later.
• The Cordova platform requirements are higher for SDK 6 integrations.
• Document scan configuration and results use barcode terminology when extracting codes as structured data.
• The standalone readable-code scan method is now a barcode scan method.
• Barcode scan results now use result.barcodes.
• Scan-flow errors use aligned SDK 6 string codes; user cancellation is surfaced as cancellation_error.

Requirements

• Update the plugin to @thegrizzlylabs/cordova-plugin-genius-scan@6.0.0-beta11.
• Use cordova-ios 8 or later if you want the v6 Swift Package Manager integration on iOS.
• Use cordova-android 15 or later for SDK 6 Android builds.
• Make sure the native projects satisfy the SDK 6 requirements: iOS 15 or later and Android API 23 or later.

cordova plugin rm @thegrizzlylabs/cordova-plugin-genius-scan
cordova plugin add @thegrizzlylabs/cordova-plugin-genius-scan@6.0.0-beta11

If your app pins Cordova platform versions in config.xml, update them as well:

<preference name="deployment-target" value="15.0" />
<preference name="android-minSdkVersion" value="23" />

<engine name="ios" spec="~8.0.0" />
<engine name="android" spec="~15.0.0" />

If dependency resolution behaves unexpectedly after the upgrade, remove node_modules/, platforms/, and plugins/, then run cordova prepare again.

Document scanning

Keep using cordova.plugins.GeniusScan.scanWithConfiguration(...) for document scanning.

If your SDK 5 document scan flow extracted readable codes as structured data, update that configuration and result access to barcode terminology.

Before:

cordova.plugins.GeniusScan.scanWithConfiguration(
  {
    source: 'camera',
    structuredData: ['readableCode'],
    structuredDataReadableCodeTypes: ['qr', 'code128'],
  },
  function(result) {
    var codes = result.scans[0].structuredData.readableCodes;
  },
  onError
);

After:

cordova.plugins.GeniusScan.scanWithConfiguration(
  {
    source: 'camera',
    structuredData: ['barcode'],
    structuredDataBarcodeTypes: ['qr', 'code128'],
  },
  function(result) {
    var barcodes = result.scans[0].structuredData.barcodes;
  },
  onError
);

For the complete configuration surface, see the @thegrizzlylabs/cordova-plugin-genius-scan package documentation.

Barcode scanning

Rename the readable-code API to the barcode API.

Before:

cordova.plugins.GeniusScan.scanReadableCodesWithConfiguration(
  configuration,
  function(result) {
    var codes = result.readableCodes;
  },
  onError
);

After:

cordova.plugins.GeniusScan.scanBarcodesWithConfiguration(
  configuration,
  function(result) {
    var codes = result.barcodes;
  },
  onError
);

Error handling

In SDK 5, Cordova received scan-flow failures as strings. The native cancellation code was not exposed to JavaScript, so apps that suppressed document scan cancellation usually matched the platform message: Scanning cancelled by user on iOS and Scanning canceled by user on Android.

SDK 6 aligns scan-flow error codes across iOS and Android. Cordova receives those codes on the error object: cancellation_error, configuration_error, licensing_error, capture_error, storage_space_error, and internal_error.

Before:

function isSdk5DocumentScanCancellation(error) {
  return error === 'Scanning cancelled by user' ||
    error === 'Scanning canceled by user';
}

function onScanFlowError(error) {
  if (isSdk5DocumentScanCancellation(error)) {
    return;
  }

  showScanError(error || 'Unable to scan');
  throw error;
}

After:

function onScanFlowError(error) {
  if (error && error.code === 'cancellation_error') {
    return;
  }

  showScanError((error && error.message) || 'Unable to scan');
  throw error;
}

Final checks

After updating the plugin and preparing the native platforms, build and run the app on both iOS and Android.

Validate the document scan flow, barcode scan flow, barcode result property, user cancellation handling, and one non-cancellation error callback path. If your app uses OCR, PDF generation, multi-page scanning, or structured data extraction, run those scenarios too.