> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/sdks/sdk-web/preguntas-y-errores-frecuentes.md).

# Frequently asked questions and errors

### 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**:

```ts
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:

```ts
// 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`:

```typescript
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:

```typescript
<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)

```typescript
'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**

```jsx
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}
/>
```