Incorporar o chat de IA Conversacional em uma página externa no Jitterbit App Builder
Visão geral
Este guia explica como incorporar a interface de chat IA Conversacional em uma página web externa, como um site voltado para o cliente ou uma aplicação de terceiros. Essa abordagem difere da bolha de chat e do painel de chat, que são exibidos no próprio App Builder.
O embed é implementado como um componente web (<jitterbit-chat>) carregado por meio de um pacote JavaScript fornecido pela sua instância do App Builder. O chat incorporado pode funcionar como o usuário anônimo integrado, ou autenticar usuários com SSO JWT baseado na sessão da página host. Esta página descreve ambas as opções.
Pré-requisitos
O chat incorporado requer App Builder 4.63 ou posterior. Antes de incorporar o chat em uma página externa, conclua o seguinte:
- Conectar um agente de IA como fonte de dados de API REST no App Builder.
- Configurar um agente de IA Conversacional no IDE com a opção Is Active habilitada.
Como incorporar o chat em uma página externa
Siga as etapas abaixo para incorporar o chat em uma página externa. As etapas diferem conforme você deseje que o chat incorporado funcione como um usuário anônimo ou se pretenda configurar a autenticação SSO JWT:
Etapa 1: Adicionar o snippet de embed
Para incorporar o chat em uma página externa, adicione o seguinte ao seu HTML:
<script src="{base-url}/js/jitterbit-chat-loader.bundle.js" defer></script>
<jitterbit-chat
base-url="{base-url}"
agent-ids="">
</jitterbit-chat>
Substitua o seguinte espaço reservado:
{base-url}: A URL da sua instância do App Builder.
Nota
O título exibido na janela do chat é o nome do agente ativo, conforme configurado no IDE.
O atributo agent-ids é opcional. Deixe-o vazio para exibir todos os agentes disponíveis para o usuário, ou insira um ou mais IDs de agente como uma lista separada por vírgula para limitar o chat a agentes específicos.
Etapa 2: Escolher um método de acesso
O chat incorporado suporta dois modos de acesso. Escolha aquele que se adequa aos seus requisitos:
Opção A: Acesso anônimo
Por padrão, o chat incorporado funciona como o usuário anonymous integrado. No entanto, você precisa permitir que usuários anônimos interajam com o chat. Crie um grupo dedicado e conceda a ele os privilégios apropriados seguindo estas etapas:
- No IDE, clique em User Management no painel Runtime.
- Selecione a guia Groups e clique em + Group.
-
Digite um nome (por exemplo,
Anonymous Users) e uma descrição, depois clique em Save.
-
Quando o novo grupo aparecer no painel Groups, clique no seu botão Manage Privileges.
- No diálogo Manage Privileges, clique em Create no painel Privileges.
- No diálogo Create Privilege, selecione Application no campo Type.
-
No dropdown Application, selecione Vinyl - Custom Agents, depois clique em Save.

-
Selecione o novo privilege no painel Privileges. As funções associadas a ele aparecem no painel Roles.
- Localize a função Agent Chat e clique em Grant.
-
Saia do diálogo para retornar à guia Groups. Com o novo grupo selecionado no painel Groups, clique em + Membership no painel Membership. Selecione o usuário
anonymousintegrado no dropdown User, e clique em para salvar.
Para mais informações sobre como gerenciar grupos e privilégios, consulte Gerenciamento de Usuários e Grupos.
Nota
Se a página do host for servida de um hostname diferente da sua instância do App Builder, configure CORS no servidor web voltado para o público na frente do App Builder (por exemplo, IIS no Windows ou Apache no Linux). Entre em contato com seu time de infraestrutura ou consulte a documentação do seu servidor web para as etapas de configuração.
Em seguida, adicione uma função e conceda as permissões relevantes seguindo estas etapas:
- No IDE, clique em Data Servers no painel Connect.
- Na lista de data servers, selecione o data server do agente de IA.
- No painel à direita, clique duas vezes na caixa contendo o nome do servidor ou clique no ícone na caixa. Uma caixa de diálogo é aberta.
-
Clique em Roles. A caixa de diálogo Roles é aberta.

-
No painel Role, em Role Information, insira um Name para a nova função e clique em Save.
- No painel Permissions, clique em + Permission.
- Em Table, selecione o endpoint principal do data server do agente de IA (por exemplo,
chat). Não selecione tabelas secundárias comochat/referencesouchat/ResponseHeaders, que são usadas internamente pelo App Builder. -
Verifique se Read, Insert, Update e Delete estão todos selecionados e clique em para salvar.

Por fim, conceda ao grupo Anonymous Users acesso à função:
- No IDE, clique em User Management no painel Runtime.
- Selecione a aba Groups e clique no grupo Anonymous Users.
- Clique em Manage Privileges.
- No painel Privileges, clique em Create.
- Na caixa de diálogo Create Privilege, selecione Data Source no campo Type.
-
No dropdown Data Source, selecione a fonte de dados do agente de IA e clique em Save.

-
Selecione o novo privilégio no painel Privileges. As funções associadas a ele aparecem no painel Roles.
-
Localize a função criada acima e clique em Grant.

Opção B: autenticação JWT SSO
Para autenticar usuários da página do host em vez de executar como anônimo, configure a autenticação JWT SSO. Quando o JWT SSO está ativo, o chat incorporado autentica o usuário antes de fazer chamadas REST, provisiona automaticamente o usuário no App Builder se ele ainda não existir e realiza silenciosamente a reautenticação quando os cookies de sessão expiram.
Primeiro, configure as configurações do IDE seguindo estas etapas:
- No IDE, clique em Security Providers no painel Connect. A página Security é aberta.
- No painel Configuration, clique em More e selecione Sites. A caixa de diálogo Sites é aberta.
- Clique em + Site.
- No campo URL, insira a URL base da sua instância do App Builder (por exemplo,
https://example.com). - Deixe a caixa de seleção Redirect desmarcada.
- Marque a caixa de seleção Allow Cross Origin.
-
Clique em Save.

Em seguida, configure um provedor JWT SSO:
- No IDE, clique em Security Providers no painel Connect. A página Security é aberta.
-
Clique em + Security Provider. A página Provider é aberta no modo de criação:
-
Na seção Settings, configure o seguinte:
- Name: insira um nome para o provedor.
- Type: selecione JWT SSO.
- Enabled: marque esta caixa de seleção.
- Na seção Tokens, configure o seguinte:
- Audience: insira a URL base da sua instância do App Builder (por exemplo,
https://example.com). - Issuer: insira o valor do emissor configurado nas configurações de geração de JWT da página do host (por exemplo,
example.com). Isso deve corresponder à reivindicaçãoissnos JWTs emitidos pelo framework de autenticação da página do host.
- Audience: insira a URL base da sua instância do App Builder (por exemplo,
- Na seção Provisioning, marque as caixas de seleção User Provisioning e Supplies Group Membership.
- Clique em Save para criar o provedor.
- No painel Certificates, clique em + Certificate (consulte Provedor de segurança JWT SSO para detalhes sobre requisitos de certificado) e configure o seguinte:
- Uso: Selecione Validação de Assinatura.
- Tipo: Selecione Certificado X.509.
- Formato: Selecione PEM.
- Conteúdo: Cole o certificado codificado em PEM que contém a chave pública RSA usada para assinar os JWTs emitidos pela estrutura de autenticação da página host.
- Identificador: Opcionalmente, insira um identificador para o certificado. Se especificado, esse valor aparece no parâmetro
kiddos cabeçalhos JWT.
Clique em Salvar.
Nota
O nome que você atribui ao provedor deve corresponder ao valor do atributo provider no trecho de incorporação.
Em seguida, atualize o trecho de incorporação. Adicione os atributos provider e jwt ao elemento <jitterbit-chat>:
<script src="{base-url}/js/jitterbit-chat-loader.bundle.js" defer></script>
<jitterbit-chat
base-url="{base-url}"
agent-ids=""
provider="{provider-name}"
jwt="{JWT token}">
</jitterbit-chat>
Substitua os seguintes espaços reservados:
{provider-name}: O nome do provedor JWT SSO configurado no IDE.{JWT token}: O token JWT emitido pela estrutura de autenticação da página host.
Como ocorre com usuários anônimos, usuários autenticados por JWT precisam estar autorizados a interagir com o agente de IA. Para fazer isso, comece adicionando uma função apropriada e concedendo as permissões necessárias. Siga estas etapas:
- No IDE, clique em Data Servers no painel Connect.
- Na lista de servidores de dados, selecione o servidor de dados do agente de IA.
- No painel à direita, clique duas vezes na caixa contendo o nome do servidor ou clique no ícone na caixa. Um diálogo abre.
-
Clique em Roles. O diálogo Roles abre.

-
No painel Role, em Role Information, insira um Name para a nova função e clique em Save.
- No painel Permissions, clique em + Permission.
- Em Table, selecione o endpoint principal do servidor de dados do agente de IA (por exemplo,
chat). Não selecione tabelas subsidiárias comochat/referencesouchat/ResponseHeaders, que são usadas internamente pelo App Builder. -
Verifique se Read, Insert, Update e Delete estão todos selecionados e clique em para salvar.

Por fim, conceda ao grupo de segurança acesso à função:
- No IDE, clique em User Management no painel Runtime.
- Selecione a aba Groups e clique no grupo ao qual os usuários autenticados por JWT pertencem (por exemplo, Users).
- Clique em Manage Privileges.
- No painel Privileges, clique em Create.
- No diálogo Create Privilege, selecione Data Source no campo Type.
-
No menu suspenso Data Source, selecione a fonte de dados do agente de IA e clique em Save.

-
Selecione o novo privilégio no painel Privileges. As funções associadas a ele aparecem no painel Roles.
-
Localize a função criada acima e clique em Grant.



