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