Frequently asked questions and errors

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

Turbopack Compatibility

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

Using the Bundle Version

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

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

To be able to use this module when using 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.

Solution: Use string literal values directly:

<facephi-sdk-provider
  type={'ONBOARDING'}           // en lugar de TypeFamily.onboarding
  language={'en'}               // en lugar de 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)

'use client';
import type { 
  ErrorData, 
  SelphiWidgetLoadedEvent, 
  SelphiExtractionFinishEvent, 
  FacephiSelphiWidgetCustomEvent 
} from '@facephi/sdk-web-wc';
import { defineCustomElements } from '@facephi/sdk-web-wc/bundle';

// Eventos del Provider
function handleEmitData(event: CustomEvent<{ operationId: string; sessionId: string; extraData: string }>) {
  const result = event.detail;
}

// Eventos de Selphi
function handleModuleLoaded(event: FacephiSelphiWidgetCustomEvent<SelphiWidgetLoadedEvent>) {
  const result = event.detail.detail;
}

function handleExtractionFinish(event: FacephiSelphiWidgetCustomEvent<SelphiExtractionFinishEvent>) {
  const result = event.detail.detail;
}

return (
  <facephi-sdk-provider
    apikey={apiKey}
    type={TypeFamily.onboarding}
    language={Language.en}
    onemitData={handleEmitData}
  >
    <facephi-selphi-widget
      interactible={true}
      previewImage={true}
      onModuleLoaded={handleModuleLoaded}
      onExtractionFinish={handleExtractionFinish}
    />
  </facephi-sdk-provider>
);

Compatibility with React and Angular Wrappers

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

---

Incorrect APIKEY Integration

An incorrect integration of the apikey can lead to several problems. The most common ones are described below:

1. Web Configuration Error

It is mandatory to provide Facephi with a valid web domain where the SDK will be used. 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 applied by web browsers that limits interactions between a web server and external APIs. In this case, when the client's website communicates with Facephi's licensing service, it will fail if the client's web domain is not properly configured during the APIKEY setup.

How to Avoid CORS Errors?

• Make sure the correct web domain is shared with the Facephi Support team when requesting the APIKEY.

• Deploy the SDK exclusively on the authorized domain.

---

2. Component Configuration Error

The apikey is linked to the components that the client has contracted, which are preconfigured by the Facephi Support team. If a specific component, such as Selphid or Selphi, is not enabled, those components will not be rendered 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 parameter debug in the facephi-sdk-provider. This will provide detailed logs and help identify incorrect configurations.

Example: Enable Debug

import { TrackingSteps, TypeFamily } from '@facephi/sdk-web-wc';

<facephi-sdk-provider
  apikey={process.env.FACEPHI_SDK_APIKEY}
  debug={true}
  steps={`${TrackingSteps.start},${TrackingSteps.selphiWidget},${TrackingSteps.selphidWidget},${TrackingSteps.finish}`}
  customerId={customerId}
  type={TypeFamily.onboarding}
/>