Frameworks y Samples

Implementación del SDK Web en frameworks y ejemplos.

Esta es una guía rápida de cómo utilizar la librería SDK Web en cualquier framework actual.

Aunque SDK Web es compatible con integraciones HTML vanilla, es recomendable evitar este tipo de implementaciones, dado que algunas configuraciones pueden no ser posibles por los tipos que HTML básico no controla.

TypeScript

Todos los componentes de Facephi están tipados para ser utilizados en entornos TypeScript (ya sea TypeScript plano o integrado en frameworks).

Esta configuración será útil durante la implementación de la librería. Estos tipos funcionarán en cualquier framework, pero su uso puede diferir dependiendo del entorno.

Ejemplo de uso:

Este es un ejemplo simple de uso para un entorno TS plano. Los tipos ofrecidos por los diferentes componentes pueden usarse en cualquier framework con integración TS. Esto proporcionará correcciones y funciones de autocompletado en el IDE.

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

Integración de SDK Web en frameworks

La librería SDK Web basada en Web Components puede integrarse en cualquier framework con la configuración requerida por cada entorno.

Es necesario usar el defineCustomElements que ofrece la librería para inicializar los componentes.

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

Las ayudas de tipos en un IDE podrían no mostrarse en algunas secciones HTML en frameworks. Para aprovechar estas características, se recomienda implementar la configuración de los diversos componentes en la sección de código o instalar las extensiones requeridas.

Los siguientes ejemplos son aproximaciones generalizadas, ya que cada entorno puede tener configuraciones o versiones diferentes. Una vez definidos los componentes, la integración es prácticamente la misma para todos los casos.

Angular

En implementaciones de Angular, se debe agregar el CUSTOM_ELEMENTS_SCHEMA para reconocer los componentes como elementos personalizados.

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

Existe una librería @facephi/sdk-web-angular para integraciones nativas en Angular. Consulta la sección SDK Web Angular para más información.

React / Next

En implementaciones de React / Next, para reconocer el componente personalizado del widget como un elemento HTML nativo, necesita registrarse como un elemento intrínseco. Todas sus propiedades, eventos y métodos podrían definirse de la misma manera.

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

Se ofrece una librería @facephi/sdk-web-react para integraciones nativas de React. Consulta la sección SDK Web React para más información.

Vue / Nuxt

En implementaciones de Vue / Nuxt, el componente personalizado del provider debe definirse como un elemento HTML nativo como en el siguiente ejemplo.

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

Aplicaciones Server Side rendering

En implementaciones de renderizado del Lado del Servidor (SSR), los componentes deben cargarse en el lado del cliente para evitar mal funcionamiento.

Wrappers Específicos para Framework

Si bien la librería de Componentes Web SDK (@facephi/sdk-web-wc) puede usarse en cualquier framework moderno, hay wrappers específicos de framework disponibles para React y Angular para proporcionar una experiencia de desarrollo más nativa.

En estas librerías, todos los componentes ya están definidos y listos para ser implementados. Estos paquetes usan la librería vanilla internamente, por lo que las mismas exportaciones (enums, tipos y métodos) están disponibles desde ellos.

SDK Web React

La librería SDK Web React (@facephi/sdk-web-react) proporciona wrappers específicos de React que te permiten usar los componentes de Facephi como componentes React nativos con soporte completo de TypeScript.

Instalación:

npm install @facephi/sdk-web-react

Consejo para IDE

Opcional: Agrega una importación de la librería en el archivo principal para que el IDE sepa dónde encontrar las exportaciones.

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

Ejemplo de uso:

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;

Características:

Componentes React nativos con soporte completo del ciclo de vida
Definiciones TypeScript para todos los componentes y props
Manejo de eventos amigable para React

SDK Web Angular

La librería SDK Web Angular (@facephi/sdk-web-angular) ofrece wrappers específicos de Angular que funcionan perfectamente con el sistema de componentes de Angular y el Angular Language Service.

:::note Esta librería se ofrece para integraciones de Angular 19 o versiones superiores. El equipo de Facephi no puede garantizar el rendimiento correcto en versiones anteriores. :::

Instalación:

npm install @facephi/sdk-web-angular

Consejo para IDE

Opcional: Agrega una importación de la librería en el archivo principal para que el IDE sepa dónde encontrar las exportaciones.

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

Ejemplo de uso:

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;
}

Características:

Componentes Angular nativos
Soporte completo de IntelliSense y autocompletado a través de Angular Language Service
Integración completa de TypeScript
Compatible con componentes standalone y NgModules

El SDK Web puede ser implementado en la mayoría de los frameworks actuales.

Existen dos versiones de la librería SDK Web:

SDK Web WebComponents: Librería web-components, compatible con la mayoría de frameworks y entornos.
```
<facephi-sdk-provider>
    <facephi-selphid-widget />
</facephi-sdk-provider>
```
SDK Web React: Versión de componentes react. Esta librería cuenta con todas las funcionalidades que la versión WebComponents, pero con la sintaxis aplicable a react.
```
<FacephiSdkProvider>
    <FacephiSelphidWidget />
</FacephiSdkProvider>
```

Ejemplos de programación

El equipo de Facephi ofrece un repositorio con una amplia gamma de ejemplos y finalidades de integración de los productos ofrecidos por Facephi.

Repositorio de ejemplos de programación del SDK Web: https://github.com/facephi/sdk-web-examples.

AnteriorCallbacks y resultados

SiguientePreguntas y errores frecuentes

Última actualización hace 3 meses