Customization

Web SDK customization guide

Customization of visual assets

The SDK Web animations can be configured with the property customAnimations in the <facephi-sdk-provider>.

With this property, one or more animations of the components offered by the SDK Web can be replaced:

• SDK Provider

• SelphID

• Selphi

• FileUploader

• QRWidget

For more information, see the documentation for the customAnimations property.

Example:

// Configuration example
const customAnimations = {
  sdkProvider: {
    loading: "/assets/anim/custom-loading.gif",
  },
  selphi: {
    loading: "/assets/anim/custom-loading.gif",
  },
  selphid: {
    loading: "/assets/anim/custom-loading.gif",
  }
};
  
// HTML
<facephi-sdk-provider
  customAnimations={customAnimations}
>
  (...)
</facephi-sdk-provider>

Note: If an animation is configured through this property and the direct prop (For example: customAnimations.sdkProvider.loading and loadingAnimation), the value configured in customAnimations.

Customization of styles

The SDK Provider components and those offered by it, such as Selphi and SelphID, can be customized with the following CSS variables applied to the tag facephi-sdk-provider:

Example:

The CSS configuration must be set with the correct encapsulation (global, scoped, ...). In component integrations, it is recommended to add the CSS configuration of facephi-sdk-provider and its configuration inside the component tag :host. Additionally, a global CSS configuration for the component will also work the same way.

CSS variable	Components	Description	Default value
Color variables
--backgroundColor	File Uploader, Choose Document, QR Widget, Desktop View, Error View, Finish Widget, Loading Ellipsis, Tip Widget	Main container background color	transparent
--color-state-loading	Loading Ellipsis	Provider loading animation color	#243760
--color-background-primary	File Uploader, Choose Document, QR Widget	Background color of primary elements (drop zone, dropdowns, content areas)	#ffffff
--color-background-hover	File Uploader, Choose Document	Hover background color for interactive elements	#cedafc
--color-background-disabled	File Uploader, Choose Document, QR Widget	Disabled element background color	#eaeef6
--color-text-primary	File Uploader, Choose Document, QR Widget, Desktop View, Error View, Finish Widget, Loading Ellipsis, Tip Widget	Primary text color	#1d2c4d
--color-text-secondary	File Uploader, Choose Document	Secondary text and placeholder color	#526080
--color-text-disabled	File Uploader, Choose Document, QR Widget	Disabled element text color	#afb8cc
--color-text-on-primary	File Uploader, Choose Document, QR Widget, Tip Widget	Text color on primary-colored backgrounds	#ffffff
--color-border-primary	File Uploader, Choose Document	Element border color	#ccd4e5
--color-state-error	File Uploader	Color for error states	#dd3631
--color-state-success	File Uploader	Color for success states	#0f8837
--color-icon-primary	File Uploader, Error View	Primary icon color	#243760
--color-icon-secondary	File Uploader	Secondary icon color	#7d879c
--primaryColor	Choose Document	Background color of selected elements	transparent
--secondaryColor	File Uploader, Choose Document, QR Widget, Tip Widget	Primary color for buttons and active elements	#3167fc
--tertiaryColor	File Uploader, Choose Document, QR Widget, Tip Widget	Hover and focus color for buttons	#2b50b6
Tutorial animation colors
--color-tutorial-computer-bg	Lottie Widget (Selphi, SelphID tutorials)	Computer screen background color in tutorial animations	#4c7cfc
--color-tutorial-shirt	Lottie Widget (QR, Selphi, SelphID tutorials)	Avatar clothing color in tutorial animations	#1d2c4d
--color-tutorial-avatar-bg	Lottie Widget (QR, Selphi tutorials)	Avatar background color in tutorial animations	#d5dae9
--color-tutorial-scan-line	Lottie Widget (QR tutorial)	Scan line color in the QR tutorial animation	#5fc982
--color-tutorial-earrings	Lottie Widget (QR tutorial)	Earrings and accessories color in tutorial animations	#f4a485
--color-tutorial-check	Lottie Widget (Selphi tutorial)	Success check color in the Selphi tutorial	#07a13a
--color-tutorial-progress	Lottie Widget (Selphi tutorial)	Circular progress bar color in the Selphi tutorial	#5fc982
--color-tutorial-capture	Lottie Widget (SelphID mobile tutorial)	Capture success color in the mobile tutorial	#07a13a
--color-tutorial-device-bg	Lottie Widget (SelphID desktop tutorial)	Device screen background color in the SelphID tutorial	#2b50b6
Typography variables
--wrapper-primary-font	File Uploader, Choose Document, QR Widget, Desktop View, Error View, Finish Widget, Loading Ellipsis, Tip Widget	Primary font family of the components	'Verdana', sans-serif
--title-font	File Uploader, Choose Document, QR Widget, Desktop View, Error View, Finish Widget, Loading Ellipsis, Tip Widget	Main title font	"Poppins-Semibold"
--text-font	File Uploader, Choose Document, QR Widget, Desktop View, Error View, Finish Widget, Loading Ellipsis, Tip Widget	Main text font	"Poppins-Regular"
--wrapper-font-family	File Uploader (drag-drop)	Font family for the drag-and-drop component	'Verdana', sans-serif
--wrapper-text-font-size	File Uploader	Text font size	1em
--secondary-font-weight	File Uploader	Secondary heading font weight	600
--primary-font-weight	File Uploader	Main text font weight	400
Layout variables
--wrapper-border-radius	File Uploader	Element border radius	0.5em
--height-field	Choose Document	Form field height	40px

Example:

facephi-sdk-provider {
  --color-text-primary: #000000;
  --secondaryColor: #ff6600;
  --tertiaryColor: #cc5200;
}

Note: The CSS configuration must be applied with the correct encapsulation (global, scoped, ...). In component integrations, it is recommended to add the CSS configuration of facephi-sdk-provider and its variables inside the component tag :host. Additionally, a global CSS configuration for the component will work the same way.

---

Selphi variables

These variables control the style of the Selphi component for Face Capture. All variables are applied to the tag facephi-sdk-provider.

CSS variable	Description	Default value
Color variables
--wrapper-color-background	Main widget background color	#FFFFFF
--wrapper-color-primary	Primary element color	#3167FC
--wrapper-color-secondary	Secondary element color	#FFFFFF
--wrapper-color-hover	Hover effect color	#2B50B6
--wrapper-color-primary-text	Primary text color	#1D2C4D
--wrapper-color-secondary-text	Secondary text color	#1D2C4D
--wrapper-color-progress-bar	Progress bar color during extraction	#3167FC
--wrapper-color-progress-bar-background	Background color of the progress bar around the camera stream	transparent
--wrapper-color-capture-success	Border color when the face is captured successfully	#60C782
--wrapper-color-capture-fail	Text and progress bar color when extraction fails	#F24B45
--wrapper-color-capture-warning	Failure color in the activity test during the Active Liveness challenge	#EB6A00
--wrapper-color-liveness-arrow	Directional arrow color during the activity check	#5FC982
--wrapper-color-icon	Icon color in the component	#243760
--wrapper-color-error-icon	Main error icon color in the error view	#DD3631
--wrapper-color-browser-icon-background	Browser icon background color in the BrowserError view	transparent
--wrapper-color-debug-error-message	Internal error message color when debugging is enabled	#DD3631
--wrapper-color-loading-camera-background	Camera background color before it is fully loaded into the DOM	#000000
--wrapper-color-loading	Primary color of the default loading animation	#1D2C4D
Tutorial animation colors
--wrapper-color-tutorial-background	Background color in the default tutorial animations	#EAEEF6
--wrapper-color-tutorial-progress	Progress bar color in the default tutorial animations	#5FC982
--wrapper-color-tutorial-tshirt	T-shirt color in the default tutorial animations	#3167FC
--wrapper-color-tutorial-earrings	Earrings and sunglasses color in the default tutorial animations	#F4A485
Typography variables
--wrapper-primary-font	Main text font	"Poppins-Regular"
--wrapper-primary-font-weight	Main font weight	400
--wrapper-secondary-font	Secondary text font	"Poppins-Semibold"
--wrapper-secondary-font-weight	Secondary font weight	600
--wrapper-text-font-size	Widget text font size	1em
--wrapper-title-font-size	Widget title font size	1.4em
--wrapper-line-height	Text line height	1.3125em
--wrapper-vertical-align	Vertical alignment of the text in the container	center
--wrapper-text-align	Horizontal alignment of the text in the container	center
Layout variables
--wrapper-progress-bar-width	Progress bar width	0.5em
--wrapper-border-radius	Button border radius	0.5em
--wrapper-error-icon-max-width	Maximum width of the error view icon	unset
Logo visibility
--wrapper-display-logo	Show or hide the logo (use block to show or none to hide)	none

Example:

facephi-sdk-provider {
  --wrapper-color-primary: #3f2eff;
  --wrapper-color-secondary: #ffffff;
  --wrapper-color-hover: rgb(106, 93, 250);
}

---

SelphID variables

These variables control the style of the SelphID component for Document Capture. All variables are applied to the tag facephi-sdk-provider.

CSS variable	Description	Default value
Color variables
--wrapper-color-background	Main widget background color	#FFFFFF
--wrapper-color-primary	Primary element color	#3167FC
--wrapper-color-secondary	Secondary element color	#FFFFFF
--wrapper-color-hover	Hover effect color	#2B50B6
--wrapper-color-primary-text	Primary text color	#1D2C4D
--wrapper-color-secondary-text	Secondary text color	#1D2C4D
--wrapper-color-capture-success	Border color when the document is captured successfully	#07A13A
--wrapper-color-capture-fail	Text, progress bar and document border color when extraction fails	#F24B45
--wrapper-color-capture-neutral	Border color of the document in its neutral state (by default, the primary color)	#3167FC
--wrapper-color-diagnostic-primary	Informational text background color	#EAEEF6
--wrapper-color-diagnostic-secondary	Informational text background color when cameraOverflow is enabled	#243760
--wrapper-color-background-camera	Video stream background color in the capture view	#10192B
--wrapper-color-background-preview-image	Preview image background color	#FFFFFF
--wrapper-color-camera-overflow	Widget background color in the document capture view when cameraOverflow is enabled	#10192b85
--wrapper-color-camera-overflow-filter	Widget background filter in the document capture view when cameraOverflow is enabled	#00000030
--wrapper-color-icon	Icon color in the component	#243760
--wrapper-color-error-icon	Main error icon color in the error view	#DD3631
--wrapper-color-browser-icon-background	Browser icon background color in the BrowserError view	transparent
--wrapper-color-debug-error-message	Internal error message color when debugging is enabled	#DD3631
--wrapper-color-loading	Primary color of the default loading animation	#1D2C4D
Tutorial animation colors
--wrapper-color-tutorial-background	Background color in the default tutorial animations	#3167FC
--wrapper-color-tutorial-success	Success overlay color in the default tutorial animations	#5BBF7E
Typography variables
--wrapper-primary-font	Main text font	"Poppins-Regular"
--wrapper-primary-font-weight	Main font weight	400
--wrapper-secondary-font	Secondary text font	"Poppins-Semibold"
--wrapper-secondary-font-weight	Secondary font weight	600
--wrapper-text-font-size	Widget text font size	1em
--wrapper-title-font-size	Widget title font size	1.4em
--wrapper-title-font-size-mobile	Widget title font size on mobile resolutions	1.125em
--wrapper-line-height	Text line height	1.75em
--wrapper-vertical-align	Vertical alignment of the text in the container	center
--wrapper-text-align	Horizontal alignment of the text in the container	center
Layout variables
--wrapper-document-border-width	Video stream border width	0.225em
--wrapper-diagnostic-border-width	Informational message border width	0.175em
--wrapper-border-radius	Button border radius	0.5em
--wrapper-error-icon-max-width	Maximum width of the error view icon	unset
Logo visibility
--wrapper-display-logo	Show or hide the logo (use block to show or none to hide)	none

Example:

facephi-sdk-provider {
  --wrapper-color-primary: #3f2eff;
  --wrapper-color-capture-success: #00aa00;
  --wrapper-color-diagnostic-primary: #f0f0f0;
}

---

Customization of dark mode

The SDK Provider components can be easily adapted to dark mode themes by overwriting the CSS variables with the appropriate color values. Below are examples of minimal configuration for each component category.

Dark mode for the SDK components

Apply these variables to customize File Uploader, Choose Document, QR Widget and the rest of the main SDK components in dark mode:

facephi-sdk-provider {
  /* SDK components */
  --backgroundColor: #1D2C4D;
  --color-background-primary: #17223B;
  --color-background-hover: #0E1B3D;
  --color-background-disabled: #243760;
  --color-text-primary: #ffffff;
  --color-text-secondary: #ffffff;
  --color-text-disabled: #6b7a90;
  --color-text-on-primary: #10192B;
  --color-border-primary: #3d4a6c;
  --color-state-error: #e85550;
  --color-state-success: #2d9d5f;
  --secondaryColor: #5b8def;
  --tertiaryColor: #4a6bc9;

  /* Tutorial animations */
  --color-tutorial-computer-bg: #4c7cfc;
  --color-tutorial-avatar-bg: #2B50B6;
  --color-tutorial-check: #2d9d5f;
  --color-tutorial-progress: #5fc982;
  --color-tutorial-capture: #2d9d5f;
  --color-tutorial-device-bg: #2B50B6;
  --color-tutorial-scan-line: #5fc982;
  --color-tutorial-earrings: #f4a485;

  /* Selphi and SelphID */
  --wrapper-color-background: #1D2C4D;
  --wrapper-color-primary: #5b8def;
  --wrapper-color-secondary: #1D2C4D;
  --wrapper-color-hover: #4a6bc9;
  --wrapper-color-primary-text: #ffffff;
  --wrapper-color-secondary-text: #ffffff;
  --wrapper-color-progress-bar: #5b8def;
  --wrapper-color-loading: #ffffff;
  --wrapper-color-tutorial-background: #526080;
  --wrapper-color-tutorial-success: #2d9d5f;
  --wrapper-color-diagnostic-primary: #243760;
}

Tip: You can combine these dark mode variables with a CSS media query to automatically change themes according to the user's preferences:

@media (prefers-color-scheme: dark) {
  facephi-sdk-provider {
    /* Aplica aquí las variables de modo oscuro */
  }
}

---

Language Property

The language property in this SDK provider component provides a robust and flexible approach to language selection and internationalization. It supports predefined translations for Spanish (default), English, and Portuguese, and can also be extended with custom translation files. This property accepts three types: a built-in enum Language a string (such as a URL to a translation JSON) or an object for custom configuration.

Default languages:

• is: Texts in Spanish (default value).

• in: Texts in English.

• pt: Texts in Portuguese.

Property type: Language | string | object

Supported Types and Usage

1. Language Enum

Use the predefined enum for the languages supported by default.

Usage:

<facephi-sdk-provider language={Language.en}></facephi-sdk-provider>

2. String (Translation JSON URL)

Pass a string to the language property to obtain a JSON file that contains complete or partial translations for one or more widgets within the SDK provider component.

Examples:

// Directorio local
<facephi-sdk-provider  language={'/public/assets/kr.json'}></facephi-sdk-provider>
// CDN
<facephi-sdk-provider  language={'https://your-cdn.com/assets/kr.json'}></facephi-sdk-provider>

JSON schema:

The root level must be an object containing one or more of the following widget keys:

• sdk

• selphi

• selphid

The configuration of the following components is carried out within the element sdk:

• FileUploader (Subida de ficheros).

• VideoProvider (Servicio de Video Grabación).

Each object will allow full or partial editing of the texts used within its components.

Example structure:

{
  "sdk": { ... },
  "selphi": { ... },
  "selphid": { ... },
}

Note: If none of these four keys is present, the SDK provider component will fall back to the default language: Spanish.

JSON Structure – Options

1. Default Language Selection: Specify an existing language for a widget:

{
  "sdk": "en",
  "selphi": "pt"
}

2. Partial Translation Overrides: This provides a way to override specific literals for a widget/language.

{
  "sdk": "en",
  "selphi": {
    "en": {
      "Initializing...": "Espera un segundo..."
    }
  },
  "selphid": {
    "en": {
      "Initializing...": "Espera un segundo..."
    }
  }
}

The overridden literal must match exactly an existing translation key. See the Widget Literals section for a complete list.

3. Add a New Language: To define a completely new language, provide all required literals for the corresponding widget(s).

{
  "sdk": {
    "Literal 1": "Traducción para literal 1",
    "Literal 2": "Traducción para literal 2",
    "...": "..."
  }
}

Example in Korean:

{
  "sdk": {
    "The process has been completed": "프로세스가 완료되었습니다",
    "Ready": "안녕, 친구",
    // ... todos los demás literales
  }
}

When adding a new language, you must provide all required literals for each affected widget.

4. Combination of Options: You can combine default language selections, partial overrides, and new language definitions within the same object or JSON as needed.

Example:

{
  "sdk": "en",
  "selphid": {
    "en": {
      "Initializing...": "Espera un segundo..."
    }
  },
  "recruitment": {
    "Start": "Comencemos",
    "Finish": "Fin"
    // ...resto de los literales requeridos para este widget
  }
}

3. Object (Direct Assignment)

You can also pass an object directly with the same schema as the JSON described above.

myComponent.language = {
  sdk: { /* ... */ },
  selphi: { /* ... */ }
}

Fallback Behavior

• If the provided translation (whether by URL or by object) does not contain any valid root key (sdk, selphi, selphid, recruitment), the default language will be used: Spanish.

• Any missing literal for a new language will also fall back to the default values for that literal in Spanish.

---

Literal templates

The complete list of translation literals for each widget, needed to create full or partial overrides, can be found here:

SDK Provider Literals:

Spanish

sdk-es.json

14KB

Open

English

sdk-en.json

13KB

Open

Portuguese

sdk-pt.json

14KB

Open

Template

sdk-empty.json

7KB

Open

The strings for the components are also configured in this object/file:

• FileUploader

• VideoProvider

• VideoAssistance

// Ejemplo de uso
language = {
    sdk = sdkCustomJson
}

SelphID Literals:

Spanish

selphid-es.json

5KB

Open

English

selphid-en.json

4KB

Open

Portuguese

selphid-pt.json

5KB

Open

Template

selphid-empty.json

2KB

Open

// Ejemplo de uso
language = {
    sdk = { ... },
    selphid: selphidCustomJson
}

Selphi Literals:

Spanish

selphi-es.json

8KB

Open

English

selphi-en.json

8KB

Open

Portuguese

selphi-pt.json

8KB

Open

Template

selphi-empty.json

4KB

Open

// Ejemplo de uso
language = {
    sdk = { ... },
    selphi: selphiCustomJson
}

---

Use Case Examples

Change Component to English

<facephi-sdk-provider  language={Language.en}></facephi-sdk-provider>

Add Korean Using a CDN JSON

<facephi-sdk-provider  language={'https://your-cdn.com/assets/kr.json'}></facephi-sdk-provider>

Where kr.json es:

{
  "sdk": {
    // ... Traducciones coreanas para todos los literales del SDK
  }
}

Combine Different Scenarios

{
  "sdk": "en",
  "selphi": {
    "en": {
      "Starting camera...": "Preparando la cámara...",
      "Initializing...": "Espera un segundo..."
    }
  },
  "recruitment": {
    // ...conjunto completo de literales chinos requeridos
  }
}

Notes and Recommendations

• When overriding or adding translations, make sure all required literals are provided for the desired widget to ensure a complete user experience in the new language.

• For consistent results, make sure the literal keys match exactly those in the default translation packages.

• If a translation package or a schema does not meet the requirements, the fallback (Spanish) will be applied.

Appendix

See the Widget Literals Reference for a complete list of translation keys for each widget separately in its customization section.

---

Helpful customization tips

Loading animation customization

It is possible to modify the default animations (change colors) or replace them with custom animations.

Change the color of loading animations

To change the color of the animations, use the CSS variables provided for that purpose:

• SDK Provider (Loading Ellipsis): --color-state-loading.

• Selphi and SelphID components: --wrapper-color-loading.

Change loading animation

Loading animations can be replaced through the property loadingAnimation.

This property is available for the components:

• SDK Provider (link).

• SelphID Widget (link).

• Selphi Widget (link).

---

Hide loading times

When using a custom loading screen instead of the default ones provided by the SDK components, it is possible to hide the loading screens with an overlay until the first widget is fully loaded. This can be controlled via the widgets' "load end" events.

Example (JSX): overlay controlled by state; it is hidden when SelphID emits prefix.

<div class="container">
  {showLoadingOverlay && <custom-loader />}
  <facephi-sdk-provider>
    <facephi-selphid-widget
      onModuleLoaded={handleSelphIDLoaded}
    />
  </facephi-sdk-provider>
</div>

let showLoadingOverlay = true;

function handleSelphIDLoaded(ev) {
  let showLoadingOverlay = false;
}

Note: The loading of the next component (usually Selphi) can be hidden in the same way, or by customizing the widget's loading animation using the property loadingAnimation.

Warning: Make sure this overlay does not cover any possible components, error screens, or error flows. This behavior is the responsibility of the implementer.