For the complete documentation index, see llms.txt. This page is also available as Markdown.

Frequently asked questions and errors

This section describes some of the most common issues that may arise when integrating the SDK Web.

Turbopack Compatibility

Some modern frameworks, such as Next.js 16, use Turbopack as their default bundler. Turbopack currently has some limitations that cause compatibility issues with the standard distribution of the SDK Web.

Using the Bundle Version

To use the SDK Web with Turbopack-enabled frameworks, you must import from the bundle:

import { defineCustomElements } from '@facephi/sdk-web-wc/bundle';

To use this module with TypeScript, it must be declared in a .d.ts file as follows:

// global.d.ts
declare module '@facephi/sdk-web-wc/bundle';

However, it has some limitations, described below.

Type Import Considerations

You can import pure TypeScript types from the main package using import type:

import type { ErrorData, SelphiWidgetLoadedEvent, SelphiExtractionFinishEvent } from '@facephi/sdk-web-wc';

However, enums such as Language and TypeFamily cannot be imported from @facephi/sdk-web-wc.

Workaround: Use string literals directly:

<facephi-sdk-provider
  type={'ONBOARDING'}           // instead of TypeFamily.onboarding
  language={'en'}               // instead of Language.en
>

Warning: Not all properties accept this type of configuration. This is only valid for properties with simple values (string, number, boolean...).

Example (Implementation in Next.js 16)

Compatibility with React and Angular Wrappers

The packages @facephi/sdk-web-react and @facephi/sdk-web-angular currently are not compatible with Turbopack because they internally import from @facephi/sdk-web-wc (not the bundled version), which causes the same compatibility issues. For Turbopack environments, use native Web Components with the bundled version and manual event handling, as shown above.


Incorrect API Key Integration

Incorrect integration of the apikey can lead to several issues. The most common ones are described below:

1. Web Configuration Error

Providing Facephi with a valid web domain where the SDK will be used is mandatory. If the SDK is deployed on a different web domain, you will encounter a known web browser error called CORS (Cross-Origin Resource Sharing).

What is CORS?

CORS is a security restriction enforced by web browsers that limits interactions between a web server and external APIs. In this case, when the client's website communicates with the Facephi licensing service, it will fail if the client's web domain was not correctly configured during API key setup.

How to Avoid CORS Errors

  • Make sure to share the correct web domain with the Facephi Support team when requesting the API key.

  • Deploy the SDK exclusively on the authorized domain.


2. Component Configuration Error

The apikey is linked to the components the client has licensed, which are preconfigured by the Facephi Support team. If a specific component, such as SelphID or Selphi, is not enabled, those components will not render on the website, even if they have been integrated at the code level.

Debugging Component Configuration Errors

To debug these errors, you can enable the debug parameter in the facephi-sdk-provider. This will provide detailed logs and help identify incorrect configurations.

Example: Enabling Debug

Last updated