> 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-pt-br/sdks/sdk-web/frameworks-y-samples.md).

# Frameworks e Samples

Este é um guia rápido de como usar a biblioteca SDK Web em qualquer framework atual.

{% hint style="warning" %}
Embora SDK Web seja compatível com integrações HTML vanilla, é recomendável evitar esse tipo de implementação, já que algumas configurações podem não ser possíveis devido aos tipos que o HTML básico não controla.
{% endhint %}

## TypeScript <a href="#typescript" id="typescript"></a>

Todos os componentes de Facephi são tipados para serem usados em ambientes TypeScript (seja TypeScript puro ou integrado em frameworks).

Essa configuração será útil durante a implementação da biblioteca. Esses tipos funcionarão em qualquer framework, mas seu uso pode variar dependendo do ambiente.

**Exemplo de uso**:

Este é um exemplo simples de uso para um ambiente TS puro. Os tipos oferecidos pelos diferentes componentes podem ser usados em qualquer framework com integração TS. Isso fornecerá correções e funções de autocompletar no IDE.

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

***

## Integração de SDK Web em frameworks <a href="#integraciones-de-frameworks" id="integraciones-de-frameworks"></a>

A biblioteca SDK Web baseada em Web Components pode ser integrada em qualquer framework com a configuração exigida por cada ambiente.

É necessário usar o `defineCustomElements` que a biblioteca oferece para inicializar os componentes.

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

As sugestões de tipos em um IDE podem não ser exibidas em algumas seções HTML em frameworks. Para aproveitar esses recursos, recomenda-se implementar a configuração dos diversos componentes na seção de código ou instalar as extensões necessárias.

Os exemplos a seguir são aproximações generalizadas, já que cada ambiente pode ter configurações ou versões diferentes. Uma vez definidos os componentes, a integração é praticamente a mesma para todos os casos.

### Angular <a href="#angular" id="angular"></a>

Em implementações de Angular, deve-se adicionar o `CUSTOM_ELEMENTS_SCHEMA` para reconhecer os componentes como elementos personalizados.

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

> Existe uma biblioteca `@facephi/sdk-web-angular` para integrações nativas em Angular. Consulte a seção [SDK Web Angular](#sdk-web-angular) para mais informações.

### React / Next <a href="#react--next" id="react--next"></a>

Em implementações de React / Next, para reconhecer o componente personalizado do widget como um elemento HTML nativo, ele precisa ser registrado como um elemento intrínseco. Todas as suas propriedades, eventos e métodos poderiam ser definidos da mesma forma.

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

> É oferecida uma biblioteca `@facephi/sdk-web-react` para integrações nativas de React. Consulte a seção [SDK Web React](#sdk-web-react) para mais informações.

### Vue / Nuxt <a href="#vue--nuxt" id="vue--nuxt"></a>

Em implementações de Vue / Nuxt, o componente personalizado do provider deve ser definido como um elemento HTML nativo como no exemplo a seguir.

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

### Aplicações de renderização no lado do servidor <a href="#renderizado-del-lado-del-servidor" id="renderizado-del-lado-del-servidor"></a>

Em implementações de renderização no lado do servidor (SSR), os componentes devem ser carregados no lado do cliente para evitar mau funcionamento.

***

## Wrappers Específicos para Framework <a href="#wrappers-espec-c3-adficos-de-framework" id="wrappers-espec-c3-adficos-de-framework"></a>

Embora a biblioteca de Componentes Web SDK (`@facephi/sdk-web-wc`) possa ser usada em qualquer framework moderno, há wrappers específicos de framework disponíveis para React e Angular para proporcionar uma experiência de desenvolvimento mais nativa.

Nessas bibliotecas, todos os componentes já estão definidos e prontos para serem implementados. Esses pacotes usam a biblioteca vanilla internamente, portanto as mesmas exportações (enums, tipos e métodos) estão disponíveis a partir deles.

### SDK Web React <a href="#sdk-web-react" id="sdk-web-react"></a>

A biblioteca SDK Web React (`@facephi/sdk-web-react`) fornece wrappers específicos de React que permitem usar os componentes de Facephi como componentes React nativos com suporte completo a TypeScript.

**Instalação:**

```bash
npm install @facephi/sdk-web-react
```

**Dica para IDE**

Opcional: adicione uma importação da biblioteca no arquivo principal para que o IDE saiba onde encontrar as exportações.

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

**Exemplo de uso:**

```tsx
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 com suporte completo ao ciclo de vida
* Definições TypeScript para todos os componentes e props
* Tratamento de eventos amigável para React

### SDK Web Angular <a href="#sdk-web-angular" id="sdk-web-angular"></a>

A biblioteca SDK Web Angular (`@facephi/sdk-web-angular`) oferece wrappers específicos de Angular que funcionam perfeitamente com o sistema de componentes do Angular e o Angular Language Service.

:::note Esta biblioteca é oferecida para integrações de Angular 19 ou versões superiores. A equipe de Facephi não pode garantir o desempenho correto em versões anteriores. :::

**Instalação:**

```bash
npm install @facephi/sdk-web-angular
```

**Dica para IDE**

Opcional: adicione uma importação da biblioteca no arquivo principal para que o IDE saiba onde encontrar as exportações.

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

**Exemplo de uso:**

```typescript
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
* Suporte completo de IntelliSense e autocompletar por meio do Angular Language Service
* Integração completa de TypeScript
* Compatível com componentes standalone e NgModules

O SDK Web pode ser implementado na maioria dos frameworks atuais.

Existem duas versões da biblioteca SDK Web:

* **SDK Web WebComponents**: Biblioteca web-components, compatível com a maioria dos frameworks e ambientes.

  ```jsx
  <facephi-sdk-provider>
      <facephi-selphid-widget />
  </facephi-sdk-provider>
  ```
* **SDK Web React**: Versão de componentes react. Esta biblioteca conta com todas as funcionalidades da versão WebComponents, mas com a sintaxe aplicável a react.

  ```jsx
  <FacephiSdkProvider>
      <FacephiSelphidWidget />
  </FacephiSdkProvider>
  ```

***

## Exemplos de programação

A equipe de Facephi oferece um repositório com uma ampla gama de exemplos e finalidades de integração dos produtos oferecidos por Facephi.

Repositório de exemplos de programação do SDK Web: <https://github.com/facephi/sdk-web-examples>.