Native SDKs Troubleshooting

Introduction​

Welcome to the Fortface native SDKs troubleshooting page. Here you will find solutions for common errors, configuration issues, and frequent questions related to the Android and iOS SDKs.

General issues​

The issues below affect any SDK, regardless of platform.

Error when starting a session​

Symptom: when calling startSession, the SDK returns a validation error indicating the sessionKey is invalid.

Root cause: the app receives sessionToken, sessionKey, and sessionId from the API, but the sessionKey is altered (e.g., removing \n, applying trim, re-escaping quotes, changing encoding, compacting JSON, or passing through inputs/serializations that transform the text).

Quick diagnosis

  • In the failing environment, paste the sessionKey exactly as returned by the API; if it works, the transport mutated it.
  • Compare (hash or size) the key received vs. the key delivered to the SDK; any difference means mutation.
  • Check transport layers (forms, JSON.stringify/parse, sanitizers, storage) that might strip newlines or escape characters.

Fix

  1. Confirm the three fields (sessionToken, sessionKey, sessionId) reach the front unchanged.
  2. Ensure the sessionKey is stored and passed to the SDK exactly as received, including newlines.
  3. Avoid validation, parsing, restructuring, or sanitizing the sessionKey—treat it as an opaque blob.

Android SDK integration issues​

The issues below affect only the Android SDK.

Symptom: when starting the SDK, the app seems to open another screen/Activity, as if leaving the current flow.

Root cause: the main Activity android:launchMode is likely standard (default), creating a new instance when the SDK starts.

Fix

  1. In AndroidManifest.xml, set the main Activity to singleTop:
<activity
    android:name=".MainActivity"
    android:launchMode="singleTop">
</activity>
  1. Recompile and verify the flow stays in the same Activity.

“There's something wrong!” exception when starting the SDK​

Symptom: start() throws "There's something wrong!" when isDebugMode is false.

Root cause: the app is still perceived as a debug (or hybrid) build even when trying to start the SDK in “production”.

Diagnostic checklist

  • Is the current build variant debuggable in build.gradle?
  • Was the app signed with a debug keystore?
    • Run apksigner verify --print-certs <app-release.apk> to check.
    • A debug keystore will show something like CN=Android Debug, O=Android, C=US
  • Did R8/ProGuard remove metadata or rewrite flags the SDK uses to validate the environment?
  • Are there release+debug flavor mixes or hybrid APKs (RN/Flutter/Capacitor)?

Fix

  1. Ensure the production build is not debuggable true and is signed with the release keystore.
  2. Test a release APK without the shrinker (R8/ProGuard); if the error disappears, adjust rules or disable optimizations that remove critical metadata.
  3. Use isDebugMode=false only when the app is truly a release build.

SDK stopped working after obfuscation (ProGuard/R8)​

The Fortface SDK is already obfuscated and minified internally. However, in your app’s release build, tools like R8/ProGuard can rename or remove critical classes, causing silent failures. Add keep rules to prevent this.

Add this rule to proguard-rules.pro:

-keep class br.com.fortface.sdk.** { *; }

After applying:

  • Clean and build a release APK.
  • Test the SDK flow; if issues persist, check for global rules removing reflective resources.
Last updated on