Frameworks and Samples

Web SDK implementation in frameworks and examples.

This is a quick guide on how to use the SDK Web library in any current framework.

Although SDK Web is compatible with vanilla HTML integrations, it is recommended to avoid this type of implementation, since some configurations may not be possible due to the types that basic HTML does not handle.

TypeScript

All Facephi components are typed to be used in TypeScript environments (whether plain TypeScript or integrated into frameworks).

This configuration will be useful during the library implementation. These types will work in any framework, but their use may differ depending on the environment.

Usage example:

This is a simple usage example for a plain TS environment. The types offered by the different components can be used in any framework with TS integration. This will provide fixes and autocomplete functions in the IDE.

const facephiSdkProvider: HTMLFacephiSdkProviderElement = document.createElement('facephi-sdk-provider');
facephiSdkProvider.apikey = process.env.FACEPHI_SDK_APIKEY;
facephiSdkProvider.addEventListener('emitData', handleEmitData);

---

SDK Web Integration in frameworks

The SDK Web library based on Web Components can be integrated into any framework with the configuration required by each environment.

It is necessary to use the defineCustomElements that the library offers to initialize the components.

import { defineCustomElements as defineFacephiSdkCustomComponent } from '@facephi/sdk-web-wc/loader';
defineFacephiSdkCustomComponent(window);

Type hints in an IDE might not be displayed in some HTML sections in frameworks. To take advantage of these features, it is recommended to implement the configuration of the various components in the code section or install the required extensions.

The following examples are generalized approaches, since each environment may have different configurations or versions. Once the components are defined, integration is practically the same in all cases.

Angular

In Angular implementations, you must add the CUSTOM_ELEMENTS_SCHEMA to recognize components as custom elements.

// App-component.ts
@Component({
    selector: 'AppComponent',
    schemas: [CUSTOM_ELEMENTS_SCHEMA],
    templateUrl: './App-component.html',
    // ...
})
export class AppComponent {
  //...
}

There is a library @facephi/sdk-web-angular for native Angular integrations. See the section SDK Web Angular for more information.

React / Next

In React / Next implementations, to recognize the custom component of the widget as a native HTML element, it needs to be registered as an intrinsic element. All its properties, events, and methods could be defined in the same way.

// facephi-wdk-provider.d.ts
declare namespace JSX {
  interface IntrinsicElements {
    'facephi-sdk-provider': React.DetailedHTMLProps<
      React.HTMLAttributes<HTMLFacephiSDKProviderElement>,
      HTMLFacephiSDKProviderElement
    >;
  }
}

There is a library @facephi/sdk-web-react for native React integrations. See the section SDK Web React for more information.

Vue / Nuxt

In Vue / Nuxt implementations, the provider custom component must be defined as a native HTML element as in the following example.

// vue.config.js
module.exports = {
  (...)
  chainWebpack: (config) => {
    compilerOptions: {
      isCustomElement: (tag) => tag.startsWith('facephi-sdk-provider'),
    },
  };
},

Server-side rendering applications

In server-side rendering (SSR) implementations, components must be loaded on the client side to avoid malfunction.

---

Framework-Specific Wrappers

Although the Web Components SDK library (@facephi/sdk-web-wc) can be used in any modern framework, there are framework-specific wrappers available for React and Angular to provide a more native development experience.

In these libraries, all the components are already defined and ready to be implemented. These packages use the vanilla library internally, so the same exports (enums, types, and methods) are available from them.

SDK Web React

The SDK Web React library (@facephi/sdk-web-react) provides React-specific wrappers that allow you to use Facephi components as native React components with full TypeScript support.

Installation:

npm install @facephi/sdk-web-react

IDE Tip

Optional: Add a library import in the main file so the IDE knows where to find the exports.

import "@facephi/sdk-web-react";
import "@facephi/sdk-web-wc";

Usage example:

import React from 'react';
import { SDKProvider, SelphidWidget } from '@facephi/sdk-web-react';

function App() {
  return (
    <SDKProvider apikey={process.env.FACEPHI_SDK_APIKEY}>
      <SelphidWidget />
    </SDKProvider>
  );
}

export default App;

Features:

• Native React components with full lifecycle support

• TypeScript definitions for all components and props

• React-friendly event handling

SDK Web Angular

The SDK Web Angular library (@facephi/sdk-web-angular) offers Angular-specific wrappers that work seamlessly with Angular's component system and the Angular Language Service.

:::note This library is offered for Angular 19 or later integrations. The Facephi team cannot guarantee correct performance in earlier versions. :::

Installation:

npm install @facephi/sdk-web-angular

IDE Tip

Optional: Add a library import in the main file so the IDE knows where to find the exports.

import "@facephi/sdk-web-angular";
import "@facephi/sdk-web-wc";

Usage example:

import { Component } from '@angular/core';
import { SDKProviderComponent, SelphidWidgetComponent } from '@facephi/sdk-web-angular';

@Component({
  selector: 'app-root',
  template: `
    <facephi-sdk-provider [apikey]="apiKey">
      <facephi-selphid-widget></facephi-selphid-widget>
    </facephi-sdk-provider>
  `,
  standalone: true,
  imports: [SDKProviderComponent, SelphidWidgetComponent]
})
export class AppComponent {
  apiKey = process.env.FACEPHI_SDK_APIKEY;
}

Features:

• Native Angular components

• Full IntelliSense and autocomplete support through Angular Language Service

• Full TypeScript integration

• Compatible with standalone components and NgModules

The SDK Web can be implemented in most current frameworks.

There are two versions of the SDK Web library:

• SDK Web WebComponents: web-components library, compatible with most frameworks and environments.

  <facephi-sdk-provider>
      <facephi-selphid-widget />
  </facephi-sdk-provider>

• SDK Web React: React component version. This library has all the functionality of the WebComponents version, but with the syntax applicable to React.

  <FacephiSdkProvider>
      <FacephiSelphidWidget />
  </FacephiSdkProvider>

---

Programming examples

The Facephi team offers a repository with a wide range of examples and purposes for integrating the products offered by Facephi.

Web SDK programming examples repository: https://github.com/facephi/sdk-web-examples.