--- title: Embedding Guide slug: embedding-guide description: This document highlights the importance of documenting crucial use cases, configuring connectors, and thoroughly testing flow and steps. Furthermore, it proposes the inclusion of a helpful tooltip for the connections field and the implementation of a dese icon: {"lucideIcon":"Puzzle"} docTags: createdAt: 2023-03-10T00:56:48.000Z --- # Incorporando a Fluid no seu produto A Fluid foi projetada para ser incorporada diretamente no seu produto. Seus customers vivenciam a Fluid como parte nativa da sua aplicação — sem credenciais separadas, sem logins adicionais e sem troca de contexto. Existem duas formas de incorporar a Fluid, dependendo do quanto de controle você quer sobre a experiência do usuário. *** ## Cenários de integração ### Cenário 1 — White-label Você redireciona seu customer para o console hospedado da Fluid (`console.fluidapi.io`), que abre em uma nova aba ou frame. A Fluid cuida de toda a interface. **Ideal para:** times que querem uma experiência de integração completa sem nenhum trabalho de frontend. ```javascript Sua aplicação ──(redirect)──► console.fluidapi.io (interface hospedada pela Fluid) ``` ### Cenário 2 — SDK Incorporada Você constrói sua própria interface usando a SDK de browser da Fluid (`@fluidapi/js`). Seus customers nunca saem da sua aplicação. Você tem controle total sobre design, layout e experiência do usuário. **Ideal para:** times que querem entregar uma experiência profundamente nativa e manter o customer journey dentro do próprio produto. ```javascript Sua aplicação ──(chamadas de API)──► API Fluid (@fluidapi/js) (sua UI, seu design) ``` Ambos os cenários usam o mesmo modelo de autenticação e a mesma API. A diferença está apenas em quem renderiza a interface. *** ## Como funciona a autenticação A Fluid autentica seus customers através do seu sistema de autenticação existente. **Seus customers nunca criam uma conta na Fluid nem gerenciam** **credenciais Fluid.** O fluxo é direto: ```javascript 1. Seu backend identifica o customer (ele já está logado na sua aplicação) 2. Seu backend solicita um token de acesso de curta duração à Fluid 3. Esse token é repassado ao seu frontend 4. Seu frontend o usa para acessar a Fluid em nome do customer ``` Sem redirecionamentos para uma página de login externa. Sem telas de consentimento OAuth. Sem senha adicional para seu customer memorizar. ### O que você precisa no seu backend Uma única chamada de API usando a SDK server-side: ```js import { FluidSDK } from '@fluidapi/sdk' const fluid = new FluidSDK({ clientId: process.env.FLUID_CLIENT_ID, clientSecret: process.env.FLUID_CLIENT_SECRET, }) const { token } = await fluid.users.issueToken({ externalId: 'user-123', // seu ID interno de usuário customerExternalId: 'acme', // seu ID interno de customer/organização email: 'alice@acme.com', }) ``` É isso. Você recebe um token. Repasse ao seu frontend. *** ## Cenário 1 — White-label: guia de implementação **Passo 1 — Emita um token no seu backend** ```js const { token } = await fluid.users.issueToken({ externalId, customerExternalId }) ``` **Passo 2 — Monte a URL de redirecionamento** ```js const url = `https://console.fluidapi.io#token=${token}` ``` **Passo 3 — Direcione seu customer** Abra a URL em uma nova aba, um iframe ou um redirecionamento completo. A Fluid cuida do restante. O token é válido por 5 minutos e é de uso único — torna-se inválido no momento em que o console carrega. *** ## Cenário 2 — SDK Incorporada: guia de implementação **Passo 1 — Instale a SDK de browser** ```bash npm install @fluidapi/js ``` **Passo 2 — Emita um token no seu backend e exponha ao seu frontend** ```js // Endpoint no seu backend app.get('/fluid-token', requireAuth, async (req, res) => { const { token } = await fluid.users.issueToken({ externalId: req.user.id, customerExternalId: req.user.customerId, }) res.json({ token }) }) ``` **Passo 3 — Autentique no seu frontend** ```js import { FluidJS } from '@fluidapi/js' const fluid = new FluidJS({ baseUrl: 'https://id.api.fluidapi.io' }) // Obtenha o token do seu backend e autentique const { token } = await fetch('/fluid-token').then(r => r.json()) await fluid.authenticate({ token }) ``` **Passo 4 — Comece a chamar a API Fluid** ```js // Liste as ativações de flowkits do seu customer const flowkits = await fluid.flowkits.list() // Crie uma conexão ou fluxo para esse customer const flow = await fluid.flows.create({ name: 'Meu fluxo' }) ``` O gerenciamento de sessão é responsabilidade da SDK. Os access tokens são armazenados em memória e renovados automaticamente antes de expirar. Você chama `fluid.flowkits.list()` e sempre recebe uma resposta válida — a SDK cuida do restante. *** ## Segurança e conformidade com OAuth 2.0 ### Você nunca assina tokens Algumas soluções de embedding exigem que seu backend gere e assine criptograficamente JWTs usando uma chave privada que eles provisionam. Isso significa implementar assinatura RS256, gerenciar material criptográfico e lidar com rotação de chaves. A Fluid adota uma abordagem diferente: **seu backend faz uma chamada autenticada** **à API e recebe um token de volta**. Não há criptografia do seu lado. A infraestrutura da Fluid emite e assina tudo. ### Suas credenciais nunca chegam ao browser Seu `FLUID_CLIENT_ID` e `FLUID_CLIENT_SECRET` são usados exclusivamente no seu backend. Eles nunca são repassados ou armazenados no browser em nenhum momento do fluxo. O token que seu frontend recebe é um artefato de curta duração e uso único — não uma credencial. ### Tokens de sessão de uso único O token emitido por `issueToken()` só pode ser usado uma vez. No momento em que seu frontend se autentica com ele, ele é invalidado server-side. Interceptar o token após esse ponto não tem utilidade. O token também expira em 5 minutos independentemente do uso. ### Conformidade com OAuth 2.0 A autenticação da Fluid é construída sobre OAuth 2.0 (RFC 6749) e RFC 8693 (OAuth 2.0 Token Exchange). Os access tokens usados nas sessões dos seus customers são emitidos por um authorization server em conformidade com os padrões e podem ser validados por qualquer sistema compatível com OAuth 2.0 via introspection ou endpoints JWKS padrão. Isso significa que os tokens da Fluid funcionam com sua infraestrutura existente: API gateways, sistemas de logging e ferramentas de segurança que entendem OAuth 2.0 não precisam de tratamento especial. ### Renovação automática de sessão A SDK de browser gerencia o ciclo de vida completo da sessão. Os access tokens são renovados automaticamente antes de expirar usando um mecanismo de rotação server-side — o segredo de renovação nunca passa pelo browser. Da perspectiva da sua aplicação, `fluid.getAccessToken()` sempre retorna um token válido ou lança um erro caso a sessão tenha expirado e não possa ser recuperada. *** ## Comparando os dois cenários | | White-label | SDK Incorporada | | ----------------------------------- | ----------------------------------- | ---------------------------------------- | | Trabalho de frontend necessário | Nenhum | Sim | | Customização de UI | Nenhuma | Controle total | | Customer permanece na sua aplicação | Não (nova aba / frame) | Sim | | Tempo até a primeira integração | Minutos | Horas | | Recomendado para | Lançar rápido, validar a integração | Produto maduro, requisitos de UX nativos | Os dois cenários não são mutuamente exclusivos. Alguns times começam com White-label para validar a integração rapidamente e migram para a SDK Incorporada conforme o produto amadurece e os requisitos de design crescem. *** ## Próximos passos - [Instalar @fluidapi/sdk](#) — referência da SDK server-side - [Instalar @fluidapi/js](#) — referência da SDK de browser - [Referência da API](#) — documentação completa da API Fluid - [Fale com a gente](#) — se precisar de ajuda para escolher o caminho de integração ideal