Troubleshooting

Introduction​

Welcome to the Fortface SDK troubleshooting page. Here you will find solutions for common errors, configuration issues, and frequent questions related to the Web, 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.

Web SDK integration issues​

The issues below affect only the Web SDK.

DevTools freezes when inspecting the SDK​

Symptom: opening DevTools freezes or loops breakpoints when inspecting the SDK.

Root cause: production anti-fraud protections trigger continuous breakpoints when DevTools is open.

Fix

  • In development, use the Web SDK in debug-mode (single breakpoint, inspection allowed).
  • In production, always use the official version (not debug-mode), with DevTools closed for end users.

High occurrence of cameraPermissionDenied​

Symptom: the Web SDK returns cameraPermissionDenied in every attempt; the prompt does not reappear.

Root cause: the user denied permission; browsers do not re-show the popup after a denial and block new requests.

Fix

  • Do not loop retries. Handle the error and tell the user to allow the camera in browser settings and reload the page.
  • Inform in advance that the camera will be used to reduce immediate blocks.

Important considerations for WebViews​

Symptom: in a WebView the video does not appear automatically or shows a consent button, unlike a browser.

Root cause: WebViews block media autoplay; the SDK video respects that restriction.

Fix (configure before loading the page):

webView.settings.mediaPlaybackRequiresUserGesture = true // Android
webView.configuration.mediaTypesRequiringUserActionForPlayback = WKAudiovisualMediaTypeNone // iOS

SDK stuck on “please wait” and camera never opens​

Symptom: the SDK stays in “please wait” (Skeleton) and the camera never appears; the browser camera icon may turn on.

Root cause: other code called getUserMedia and kept the track active, blocking the device.

Fix

  1. If you open the camera before the SDK, close the tracks before starting:
const tracks = await navigator.mediaDevices.getUserMedia({ video: true });
// ... usage ...
tracks.getTracks().forEach(track => track.stop());
  1. After releasing, start the SDK:
fortfaceSdk.start();
fortfaceSdk.startSession(fortfaceFinishSession, sessionId, sessionKey);
  1. To check permission without locking the camera, use navigator.permissions.query({ name: "camera" }).
  2. Ensure no other component (barcode/QR, etc.) keeps the camera active in parallel.

SDK stops working in production builds​

Symptom: in dev it works, but in production the camera does not open, stays in Skeleton, or the SDK stops injecting elements/styles.

Root cause: build minification/optimization removes or alters SDK initializations (custom elements, side effects).

Fix

  • Do not minify the fortface-sdk package in node_modules. Keep the rest of the app minified.
Example (Next.js < 15 with Terser)​
// next.config.mjs
import TerserPlugin from 'terser-webpack-plugin';

const nextConfig = {
  output: 'export',
  webpack: (config, { isServer }) => {
    if (!isServer) {
      const excludeFortface = /node_modules[\\/](fortface-sdk)([\\/]|$)/;
      config.optimization = {
        ...config.optimization,
        minimize: true,
        minimizer: [
          new TerserPlugin({
            exclude: excludeFortface,
          })
        ]
      };
    }
    return config;
  }
};

export default nextConfig;

Alternative (no bundler)

  • Extract the .tgz, copy package/dist/fortface-sdk to assets/vendor, and import directly:
<script type="module" src="/vendor/fortface-sdk/fortface-sdk.esm.js"></script>
  • Add vendor/fortface-sdk/ to .eslintignore to avoid lint false positives.
Last updated on by Henrique dos Santos Scarabele