Incrustar el chat de IA conversacional en una página externa en Jitterbit App Builder

Descripción general

Esta guía explica cómo incrustar la interfaz de chat de IA conversacional en una página web externa, como un sitio web orientado al cliente o una aplicación de terceros. Este enfoque difiere de la burbuja de chat y el panel de chat, que se muestran dentro de App Builder.

La incrustación se implementa como un componente web (<jitterbit-chat>) cargado a través de un paquete JavaScript servido por tu instancia de App Builder. El chat incrustado puede ejecutarse como usuario anónimo integrado, o puede autenticar usuarios con SSO de JWT según la sesión de la página del host. Esta página describe ambas opciones.

Requisitos previos

El chat incrustado requiere App Builder 4.63 o posterior. Antes de incrustar el chat en una página externa, completa lo siguiente:

• Conecta un agente de IA como fuente de datos de API REST en App Builder.
• Configura un agente de IA conversacional en el IDE con la opción Is Active habilitada.

Cómo incrustar el chat en una página externa

Sigue los pasos a continuación para incrustar el chat en una página externa. Los pasos difieren si deseas que el chat incrustado se ejecute como usuario anónimo, o si tienes la intención de configurar la autenticación SSO de JWT:

• Paso 1: Añade el fragmento de incrustación

• Paso 2: Elige un método de acceso

  • Opción A: Acceso anónimo
  • Opción B: Autenticación SSO de JWT

Paso 1: Añade el fragmento de incrustación

Para incrustar el chat en una página externa, añade lo siguiente a tu HTML:

<script src="{base-url}/js/jitterbit-chat-loader.bundle.js" defer></script>

<jitterbit-chat
    base-url="{base-url}"
    agent-ids="">
</jitterbit-chat>

Reemplaza el siguiente marcador de posición:

• {base-url}: La URL de tu instancia de App Builder.

El atributo agent-ids es opcional. Déjalo vacío para mostrar todos los agentes disponibles para el usuario, o ingresa uno o más IDs de agente como una lista separada por comas para limitar el chat a agentes específicos.

Paso 2: Elige un método de acceso

El chat incrustado admite dos modos de acceso. Elige el que se ajuste a tus necesidades:

Opción A: Acceso anónimo

De forma predeterminada, el chat incrustado se ejecuta como el usuario anonymous integrado. Sin embargo, debes permitir que los usuarios anónimos interactúen con el chat. Crea un grupo dedicado y otórgale los privilegios apropiados siguiendo estos pasos:

1. En el IDE , haz clic en User Management en el panel Runtime.
2. Selecciona la pestaña Groups y haz clic en + Group.

3. Ingresa un nombre (por ejemplo, Anonymous Users) y una descripción, luego haz clic en Save.

   

4. Cuando el nuevo grupo aparezca en el panel Groups, haz clic en su botón Manage Privileges.

5. En el diálogo Manage Privileges, haz clic en Create en el panel Privileges.
6. En el diálogo Create Privilege, selecciona Application en el campo Type.

7. En el menú desplegable Application, selecciona Vinyl - Custom Agents, luego haz clic en Save.

   

8. Selecciona el nuevo privilegio en el panel Privileges. Los roles asociados aparecen en el panel Roles.

9. Localiza el rol Agent Chat y haz clic en Grant.

10. Sal del diálogo para volver a la pestaña Groups. Con el nuevo grupo seleccionado en el panel Groups, haz clic en + Membership en el panel Membership. Selecciona el usuario anonymous integrado en el menú desplegable User, y haz clic en para guardar.

    

Para más información sobre cómo administrar grupos y privilegios, consulta Administración de usuarios y grupos.

A continuación, añade un rol y asígnale los permisos relevantes siguiendo estos pasos:

1. En el IDE, haz clic en Data Servers en el panel Connect.
2. En la lista de servidores de datos, selecciona el servidor de datos del agente de IA.
3. En el panel de la derecha, haz doble clic en la casilla que contiene el nombre del servidor o haz clic en el icono en la casilla. Se abre un diálogo.

4. Haz clic en Roles. Se abre el diálogo Roles.

   

5. En el panel Role, bajo Role Information, introduce un Name para el nuevo rol y haz clic en Save.

6. En el panel Permissions, haz clic en + Permission.
7. Bajo Table, selecciona el endpoint principal del servidor de datos del agente de IA (por ejemplo, chat). No selecciones tablas subsidiarias como chat/references o chat/ResponseHeaders, que App Builder utiliza internamente.

8. Verifica que Read, Insert, Update y Delete estén todos seleccionados y haz clic en para guardar.

   

Finalmente, concede al grupo Anonymous Users acceso al rol:

1. En el IDE, haz clic en User Management en el panel Runtime.
2. Selecciona la pestaña Groups y haz clic en el grupo Anonymous Users.
3. Haz clic en Manage Privileges.
4. En el panel Privileges, haz clic en Create.
5. En el diálogo Create Privilege, selecciona Data Source en el campo Type.

6. En el menú desplegable Data Source, selecciona la fuente de datos del agente de IA y haz clic en Save.

   

7. Selecciona el nuevo privilegio en el panel Privileges. Los roles asociados aparecen en el panel Roles.

8. Localiza el rol creado anteriormente y haz clic en Grant.

   

Opción B: autenticación JWT SSO

Para autenticar usuarios desde la página host en lugar de ejecutarse como anónimo, configura la autenticación JWT SSO. Cuando JWT SSO está activo, el chat integrado autentica al usuario antes de realizar llamadas REST, aprovisiona automáticamente al usuario en App Builder si aún no existe y se reautentica silenciosamente cuando expiran las cookies de sesión.

Primero, configura los ajustes del IDE siguiendo estos pasos:

1. En el IDE, haz clic en Security Providers en el panel Connect. Se abre la página Security.
2. En el panel Configuration, haz clic en More y selecciona Sites. Se abre el diálogo Sites.
3. Haz clic en + Site.
4. En el campo URL, introduce la URL base de tu instancia de App Builder (por ejemplo, https://example.com).
5. Deja la casilla Redirect sin seleccionar.
6. Selecciona la casilla Allow Cross Origin.

7. Haz clic en Save.

   

A continuación, configura un proveedor JWT SSO:

1. En el IDE, haz clic en Security Providers en el panel Connect. Se abre la página Security.

2. Haz clic en + Security Provider. Se abre la página Provider en modo de creación:

   

3. En la sección Settings, configura lo siguiente:

   • Name: Introduce un nombre para el proveedor.
   • Type: Selecciona JWT SSO.
   • Enabled: Selecciona esta casilla.
4. En la sección Tokens, configura lo siguiente:
   • Audience: Introduce la URL base de tu instancia de App Builder (por ejemplo, https://example.com).
   • Issuer: Introduce el valor del emisor configurado en los ajustes de generación de JWT de la página host (por ejemplo, example.com). Debe coincidir con la reclamación iss en los JWT emitidos por el marco de autenticación de la página host.
5. En la sección Provisioning, selecciona las casillas User Provisioning y Supplies Group Membership.
6. Haz clic en Save para crear el proveedor.
7. En el panel Certificates, haz clic en + Certificate (consulta Proveedor de seguridad JWT SSO para obtener detalles sobre los requisitos de certificados) y configura lo siguiente:

• Uso: Selecciona Signature Validation.
• Tipo: Selecciona X.509 Certificate.
• Formato: Selecciona PEM.
• Contenido: Pega el certificado codificado en PEM que contiene la clave pública RSA utilizada para firmar los JWT emitidos por el marco de autenticación de la página host.
• Identificador: Opcionalmente, introduce un identificador para el certificado. Si se especifica, este valor aparece en el parámetro kid de los encabezados JWT.

Haz clic en Guardar.

A continuación, actualiza el fragmento de inserción. Añade los atributos provider y jwt al 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>

Reemplaza los siguientes marcadores de posición:

• {provider-name}: El nombre del proveedor JWT SSO configurado en el IDE.
• {JWT token}: El token JWT emitido por el marco de autenticación de la página host.

Al igual que los usuarios anónimos, los usuarios autenticados con JWT necesitan estar autorizados para interactuar con el agente de IA. Para hacerlo, comienza agregando un rol apropiado y otorgándole los permisos necesarios. Sigue estos pasos:

1. En el IDE, haz clic en Data Servers en el panel Connect.
2. En la lista de servidores de datos, selecciona el servidor de datos del agente de IA.
3. En el panel de la derecha, haz doble clic en el cuadro que contiene el nombre del servidor o haz clic en el icono en el cuadro. Se abre un diálogo.

4. Haz clic en Roles. Se abre el diálogo Roles.

   

5. En el panel Role, bajo Role Information, introduce un Name para el nuevo rol y luego haz clic en Guardar.

6. En el panel Permissions, haz clic en + Permission.
7. Bajo Table, selecciona el punto de conexión principal del servidor de datos del agente de IA (por ejemplo, chat). No selecciones tablas secundarias como chat/references o chat/ResponseHeaders, que son utilizadas internamente por App Builder.

8. Verifica que Read, Insert, Update y Delete estén todos seleccionados y luego haz clic en para guardar.

   

Finalmente, otorga al grupo de seguridad acceso al rol:

1. En el IDE, haz clic en User Management en el panel Runtime.
2. Selecciona la pestaña Groups y haz clic en el grupo al que pertenecen los usuarios autenticados con JWT (por ejemplo, Users).
3. Haz clic en Manage Privileges.
4. En el panel Privileges, haz clic en Create.
5. En el diálogo Create Privilege, selecciona Data Source en el campo Type.

6. En el desplegable Data Source, selecciona la fuente de datos del agente de IA y luego haz clic en Guardar.

   

7. Selecciona el nuevo privilegio en el panel Privileges. Los roles asociados aparecen en el panel Roles.

8. Localiza el rol creado arriba y haz clic en Grant.