Embedding Guide

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 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 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 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 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 const { token } = await fluid users issuetoken({ externalid, customerexternalid }) passo 2 — monte a url de redirecionamento 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 npm install @fluidapi/js passo 2 — emita um token no seu backend e exponha ao seu frontend // 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 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 // 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