Frameworks e exemplos

Implementação do SDK Web em frameworks e exemplos.

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

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.

TypeScript

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.

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 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.

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

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

// 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 para mais informações.

React / Next

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.

// 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 para mais informações.

Vue / Nuxt

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

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

Aplicações de renderização no lado do servidor

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

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 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:

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.

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

Exemplo 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 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 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:

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.

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

Exemplo 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

• 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.

  <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.

  <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.