> 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/sdks/sdk-web/frameworks-y-samples.md).
# Frameworks y Samples
Esta es una guía rápida de cómo utilizar la librería SDK Web en cualquier framework actual.
{% hint style="warning" %}
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.
{% endhint %}
## 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.
```ts
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.
```js
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.
```js
// 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](#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.
```js
// facephi-wdk-provider.d.ts
declare namespace JSX {
interface IntrinsicElements {
'facephi-sdk-provider': React.DetailedHTMLProps<
React.HTMLAttributes,
HTMLFacephiSDKProviderElement
>;
}
}
```
> Se ofrece una librería `@facephi/sdk-web-react` para integraciones nativas de React. Consulta la sección [SDK Web React](#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.
```js
// 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:**
```bash
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.
```js
import "@facephi/sdk-web-react";
import "@facephi/sdk-web-wc";
```
**Ejemplo de uso:**
```tsx
import React from 'react';
import { SDKProvider, SelphidWidget } from '@facephi/sdk-web-react';
function App() {
return (
);
}
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:**
```bash
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.
```js
import "@facephi/sdk-web-angular";
import "@facephi/sdk-web-wc";
```
**Ejemplo de uso:**
```typescript
import { Component } from '@angular/core';
import { SDKProviderComponent, SelphidWidgetComponent } from '@facephi/sdk-web-angular';
@Component({
selector: 'app-root',
template: `
`,
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.
```jsx
```
* **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.
```jsx
```
***
## 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: .