Troubleshooting

Introduction​

Welcome to the Fortface Web SDK troubleshooting page. Here you will find solutions for common errors, configuration issues, and frequent questions related to the Web SDK.

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.

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.

SDK with Angular has issues on iOS 26.2​

Symptom: initialization issues occur when using the fortface .tgz package.

Root cause: after the latest iOS update to version 26.

Fix: avoid using the fortface .tgz (use a bundler instead).

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.

CSP version (Content Security Policy)​

Symptom: issues using the SDK when CSP settings are enabled.

Fix:

  • Use the fortface-sdk.x.x.x-csp.tgz version. See the CSP Version page for the full list of required directives.
Last updated on