Troubleshooting issues with the iOS SDK

This page covers iOS-specific integration issues. For a symptom-based overview, start with Common Issues.

License errors

In case of an expired or invalid license, SDK methods throw an NSError in GSKErrorDomain with a GSKError code. Catch license errors separately so your app can prompt users to update or show a fallback flow:

do {
    // SDK method call
} catch let error as NSError
    where error.domain == GSKErrorDomain &&
    error.code == GSKError.licenseError.rawValue {
    // Handle expired or invalid license
    // Prompt users to update to the latest version of your app
} catch {
    // Handle other SDK errors
}

If the license key is rejected at startup, verify that it matches the app bundle identifier and that it is set before calling SDK APIs. See Configure the License Key.

Framework not found at launch

Symptoms

The app builds but crashes at launch with an error such as image not found, or Xcode reports that GSSDK cannot be loaded.

Fix

If you use Swift Package Manager, make sure the GSSDK package product is added to the app target that uses the SDK.

If you integrate the SDK manually, embed GSSDK.xcframework in the app target. It must be available in the final app bundle, not only linked during compilation.

Deployment target below iOS 15

Symptoms

Xcode or Swift Package Manager reports that GSSDK.framework requires a newer iOS version.

Fix

Set the app target deployment target to iOS 15.0 or later. If another dependency requires a higher deployment target, keep the higher value.

For cross-platform apps, update the generated or native iOS project too. For example, React Native, Flutter, Cordova, Capacitor, and .NET MAUI apps all have native iOS deployment-target settings in addition to their package dependency.

Camera permission is missing

Symptoms

The scan flow cannot access the camera, or iOS terminates the app when camera access is requested.

Fix

Add NSCameraUsageDescription to the app Info.plist:

<key>NSCameraUsageDescription</key>
<string>We use the camera to scan documents</string>

If you build a custom integration, request camera permission before initializing camera UI components.

ScanFlow UI is not localized

Symptoms

ScanFlow screens stay in English even though the device language is supported.

Fix

The ScanFlow UI supports around 20 languages and uses the device locale for user guidance, menus, and dialogs.

The SDK uses the localization of the main app. If localization is not enabled for the host app, the SDK falls back to English.

To enable localization:

1. Add each supported language to the Xcode project.
2. Make sure at least one file is localized for each language.
3. Rebuild the app and test with a device or simulator configured for that locale.

Apple documents the project setup in Localizing Your App.

Status bar appearance is broken in the scan flow

Symptoms

The status bar appearance is incorrect while the scan flow is visible.

Fix

The Genius Scan SDK supports the modern, view controller-based status bar appearance introduced with iOS 7. The camera screen is designed to work with the status bar hidden.

If the status bar appearance is broken, remove UIViewControllerBasedStatusBarAppearance=NO from your app’s Info.plist, or set it to YES.

Getting further help

If the issue persists, contact support with:

• The SDK version
• The app bundle identifier
• The Xcode version and iOS deployment target
• Complete build logs or runtime error messages
• Steps to reproduce the issue