Ir para o conteúdo

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:

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:

  1. No IDE, clique em User Management no painel Runtime.
  2. Selecione a guia Groups e clique em + Group.
  3. Digite um nome (por exemplo, Anonymous Users) e uma descrição, depois clique em Save.

    Diálogo Criar novo grupo

  4. Quando o novo grupo aparecer no painel Groups, clique no seu botão Manage Privileges.

  5. No diálogo Manage Privileges, clique em Create no painel Privileges.
  6. No diálogo Create Privilege, selecione Application no campo Type.
  7. No dropdown Application, selecione Vinyl - Custom Agents, depois clique em Save.

    Diálogo Privilege

  8. Selecione o novo privilege no painel Privileges. As funções associadas a ele aparecem no painel Roles.

  9. Localize a função Agent Chat e clique em Grant.
  10. 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 anonymous integrado no dropdown User, e clique em para salvar.

    Página Groups

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:

  1. No IDE, clique em Data Servers no painel Connect.
  2. Na lista de data servers, selecione o data server do agente de IA.
  3. 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.
  4. Clique em Roles. A caixa de diálogo Roles é aberta.

    Caixa de diálogo de função

  5. No painel Role, em Role Information, insira um Name para a nova função e clique em Save.

  6. No painel Permissions, clique em + Permission.
  7. Em Table, selecione o endpoint principal do data server do agente de IA (por exemplo, chat). Não selecione tabelas secundárias como chat/references ou chat/ResponseHeaders, que são usadas internamente pelo App Builder.
  8. Verifique se Read, Insert, Update e Delete estão todos selecionados e clique em para salvar.

    Painel de Permissões

Por fim, conceda ao grupo Anonymous Users acesso à função:

  1. No IDE, clique em User Management no painel Runtime.
  2. Selecione a aba Groups e clique no grupo Anonymous Users.
  3. Clique em Manage Privileges.
  4. No painel Privileges, clique em Create.
  5. Na caixa de diálogo Create Privilege, selecione Data Source no campo Type.
  6. No dropdown Data Source, selecione a fonte de dados do agente de IA e clique em Save.

    Caixa de diálogo de privilégio 2

  7. Selecione o novo privilégio no painel Privileges. As funções associadas a ele aparecem no painel Roles.

  8. Localize a função criada acima e clique em Grant.

    Funções concedidas

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:

  1. No IDE, clique em Security Providers no painel Connect. A página Security é aberta.
  2. No painel Configuration, clique em More e selecione Sites. A caixa de diálogo Sites é aberta.
  3. Clique em + Site.
  4. No campo URL, insira a URL base da sua instância do App Builder (por exemplo, https://example.com).
  5. Deixe a caixa de seleção Redirect desmarcada.
  6. Marque a caixa de seleção Allow Cross Origin.
  7. Clique em Save.

    Caixa de diálogo Site

Em seguida, configure um provedor JWT SSO:

  1. No IDE, clique em Security Providers no painel Connect. A página Security é aberta.
  2. Clique em + Security Provider. A página Provider é aberta no modo de criação:

    Criar um provedor

  3. 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.
  4. 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ção iss nos JWTs emitidos pelo framework de autenticação da página do host.
  5. Na seção Provisioning, marque as caixas de seleção User Provisioning e Supplies Group Membership.
  6. Clique em Save para criar o provedor.
  7. No painel Certificates, clique em + Certificate (consulte Provedor de segurança JWT SSO para detalhes sobre requisitos de certificado) e configure o seguinte:

Diálogo de certificado

  • 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 kid dos 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:

  1. No IDE, clique em Data Servers no painel Connect.
  2. Na lista de servidores de dados, selecione o servidor de dados do agente de IA.
  3. No painel à direita, clique duas vezes na caixa contendo o nome do servidor ou clique no ícone na caixa. Um diálogo abre.
  4. Clique em Roles. O diálogo Roles abre.

    Diálogo de função

  5. No painel Role, em Role Information, insira um Name para a nova função e clique em Save.

  6. No painel Permissions, clique em + Permission.
  7. Em Table, selecione o endpoint principal do servidor de dados do agente de IA (por exemplo, chat). Não selecione tabelas subsidiárias como chat/references ou chat/ResponseHeaders, que são usadas internamente pelo App Builder.
  8. Verifique se Read, Insert, Update e Delete estão todos selecionados e clique em para salvar.

    Painel de permissões

Por fim, conceda ao grupo de segurança acesso à função:

  1. No IDE, clique em User Management no painel Runtime.
  2. Selecione a aba Groups e clique no grupo ao qual os usuários autenticados por JWT pertencem (por exemplo, Users).
  3. Clique em Manage Privileges.
  4. No painel Privileges, clique em Create.
  5. No diálogo Create Privilege, selecione Data Source no campo Type.
  6. No menu suspenso Data Source, selecione a fonte de dados do agente de IA e clique em Save.

    Diálogo de privilégio 2

  7. Selecione o novo privilégio no painel Privileges. As funções associadas a ele aparecem no painel Roles.

  8. Localize a função criada acima e clique em Grant.

    Funções concedidas