Vistas web
La aptitud puede permitir a sus clientes introducir datos estructurados mediante una aplicación de Webview.
Las conversaciones en lenguaje natural son fluidas por naturaleza. Sin embargo, es posible que no siempre sean la mejor fuente de información de los usuarios para una aptitud. Por ejemplo, cuando los usuarios introducen detalles de sus tarjetas de crédito o pasaportes, tienen que introducir información específica (y precisa). Para ayudar con tareas de este tipo, la aptitud puede llamar a una aplicación de vista web.
Estas aplicaciones no solo permiten la entrada de datos estructurados mediante elementos de la interfaz de usuario, como formularios, selectores de fecha, campos y listas de valores, sino que también pueden validar la entrada del usuario y recopilar información de varias formas, como mediante la carga de imágenes, la captura de firmas de usuario o el escaneo de códigos de barras. Las aplicaciones de vista web también protegen los datos confidenciales de los usuarios, como los números de tarjetas de crédito, ya que estos datos no aparecen en el historial del chat cuando se introducen en la aplicación.
Descripción de la ilustración de vista web-webapp.png
Integración de una vista web en una aptitud
- Un servicio de vista web que conecta la aptitud con la aplicación web, que se puede alojar en un servidor web externo o en Digital Assistant.
- Un componente de vista web en el flujo de diálogo. Este componente actúa como puerta de enlace a la aplicación web asignando un nombre al servicio Webview, enumerando las variables de flujo de diálogo que se basan en la aplicación web y almacenando los valores devueltos por la aplicación web.
En tiempo de ejecución, el componente presenta un botón que inicia la aplicación web. El componente de vista web inicia la aplicación como una vista web dentro de la aptitud, o bien en un separador del explorador independiente cuando la aptitud se ejecuta en un canal web.
- La propia aplicación web, que está alojada en Digital Assistant o en un servidor web remoto.
Consejo:
Consulte el ejemplo de inicio de webhook que se describe en la documentación del SDK enhttps://oracle.github.io/bots-node-sdk/.
Vistas web alojadas en Digital Assistant
index.html) que inicia la aplicación web y se actualiza como respuesta a la entrada del usuario de la aptitud. Cuando el componente de vista web llama a una SPA:
- Se carga
index.html, que inicia la aplicación web como vista web o en un separador del explorador diferente. - A continuación, el componente Webview pasa los valores de parámetros recopilados en el flujo de diálogo junto con la dirección URL de devolución de llamada. En Activación de la SPA para acceder a los parámetros de entrada y el URL de devolución de llamada, se describen distintos métodos para transferir estos valores.
- La aplicación web realiza una solicitud POST al URL de devolución de llamada generado por el componente Webview. Esta solicitud indica que la aplicación ha completado su procesamiento. Si la aplicación devuelve datos, se incluyen en esta solicitud como un objeto JSON que se almacena en la propiedad
variable. Puede hacer referencia a estos datos en el flujo de diálogo mediante${variable_property_name.value.Param}.
Puede escribir la SPA utilizando diferentes marcos, como Oracle Visual Builder, Angular, Oracle JavaScript Extension Toolkit (JET) o React.js.
El backend de Oracle Visual Builder gestiona las conexiones de REST y los usuarios (a través de Oracle Identity Cloud Service), además de ejecutar objetos de negocio, de modo que cualquier aplicación de Oracle Visual Builder alojada en Digital Assistant presentará las siguientes limitaciones:
- No puede usar objetos de negocio.
- No se puede integrar con Oracle Identity Cloud Service.
- No puede acceder a un servicio de REST mediante el proxy de autenticación de Oracle Visual Builder.
Para alojar la aplicación en Digital Assistant, debe empaquetarla en un archivo TAR (un archivo TGZ). Debido a que se trata de una SPA, el archivo index.html debe estar en la raíz de este paquete.
Activación de la SPA para acceder a los parámetros de entrada y el URL de devolución de llamada
window.webViewParameters (mostrada en el fragmento siguiente) en el elemento <head> del archivo index.html en tiempo de ejecución. Los pares clave-valor en la carga útil informan a la SPA de los valores de entrada transferidos desde la aptitud.window.webviewParameters = {
parameters: [
{"key": "variableA", "value": "jsonObjA"},
{"key": "variableB", "value": "jsonObjB"},
...
{"key": "webview.onDone",
"value": "https://host:port/patch"},
]
};
Para permitir que la aplicación acceda a estos objetos, declare una variable window.webviewParameters['parameters']:let webviewParameters = window.webviewParameters !=null?window.webviewParameters['parameters']:null;
El objeto devuelto se almacena en la propiedad Salida para servicio de la vista web debido a la devolución de llamada.
app.js de la aplicación React, la función devuelve el valor de una clave con nombre. Si no se puede encontrar, establece un valor por defecto.
Consejo:
Puede utilizar este fragmento en su propio código. Puede utilizarvar getParam en lugar de this.getParam.
class App extends Component {
constructor(props) {
super(props);
let wvParams = window.webviewParameters['parameters'];
this.getParam = (arrParams, key, defaultValue) => {
if (arrParams) {
let param = arrParams.find(e => {
return e.key === key;
});
return param ? param.value : defaultValue;
}
return defaultValue;
};Definición de marcadores de posición en el archivo index.html
Si aloja la SPA en Digital Assistant, no tiene que definir ningún marcador de posición para los valores de variable del archivo index.html. Siempre que el archivo index.html tenga un elemento <head>, la aplicación web sabrá qué valores esperar, así como la devolución de llamada.
Adición de un solo marcador de posición al elemento <head>
Dentro del elemento <head>, inserte un bloque <script> con el marcador de posición webview.sourceVariableList. La aplicación web sustituye esto por una cadena codificada con JSON que contiene los datos del parámetro de entrada y el URL de devolución de llamada.
En el ejemplo siguiente, la clave es window.wvParams. Puede utilizar cualquier nombre para esta clave, siempre que la agregue con window. Siempre debe definir el valor como "webview.sourceVariableList".
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<meta name="theme-color" content="#000000">
<link rel="manifest" href="%PUBLIC_URL%/manifest.json">
<link rel="shortcut icon" href="%PUBLIC_URL%/favicon.ico">
<title>React App</title>
<script>
window.wvParams="webview.sourceVariableList";
</script>
</head>
En el siguiente ejemplo de código de aplicación:
- La sentencia
letasignawebview.sourceVariableListawvParams. - Los valores de salida se analizan como un objeto JSON.
fullnameextrae el nombre de la variable definida para la propiedadsourceVariableListen el componente de vista web (dondenamees el nombre de la variable definida).
class App extends Component {
constructor(props) {
super(props);
let wvParams = (window.wvParams === "webview.sourceVariableList" ?
[] : JSON.parse(window.wvParams)['parameters']);
this.getParam = (arrParams, key, defaultValue) => {
if (arrParams) {
let param = arrParams.find(e => {
return e.key === key;
});
return param ? param.value : defaultValue;
}
return defaultValue;
};
fullname = getParam(wvParams, 'name', null);
callbackurl = getParam(wvParams, 'webview.onDone', null);
...
Adición de varios marcadores de posición en el elemento <head>
Agregue un bloque <script> que tenga marcadores de posición para cada valor definido para el componente SourceVariable y la dirección URL de devolución de llamada. La aplicación web devuelve la dirección URL de devolución de llamada y los datos de los parámetros de entrada como una cadena codificada en JSON. Puesto que ha agregado marcadores de posición, no tiene que declarar una variable window.webviewParameters['parameters'].
- Parear los valores de entrada definidos para la propiedad
SourceVariable. - Contener el prefijo
webview.(webview.keyword, por ejemplo).
webview.onDone. En el siguiente fragmento, por ejemplo, webview.keyword, webview.assignee y webview.inventor coinciden con sourceVariableList: "assignee, keyword, inventor". El URL de devolución de llamada se define con webview.onDone. Puede asignar cualquier nombre a la clave de devolución de llamada, pero siempre tiene que definir el valor como webview.onDone.
Opcionalmente, puede definir variables globales añadiendo a las claves el prefijo window. (window.Keyword en el siguiente fragmento, por ejemplo).
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<meta name="theme-color" content="#000000">
<link rel="manifest" href="%PUBLIC_URL%/manifest.json">
<link rel="shortcut icon" href="%PUBLIC_URL%/favicon.ico">
<title>React App</title>
<script>
window.Keyword="webview.keyword";
window.Assignee="webview.assignee";
window.Inventor="webview.inventor";
window.CALLBACK_URL="webview.onDone";
</script>
</head>
Transmisión del URL de devolución de llamada a un botón Listo en la aplicación web
La URL de devolución de llamada generada por el componente de vista web es, básicamente, una devolución de llamada de un solo uso debido a su token de estado (https://...?state=<callback-state-token>). Si bien tiene una duración por defecto de una hora, se borrará después de que el componente Webview maneje la solicitud de devolución de llamada desde la aplicación web. Dado que los usuarios no podrán consultar la aplicación web después de este momento, debe pasar a una página final con un botón Cerrar conectado a la dirección URL de devolución de llamada.
Vistas web alojadas externamente
Una aplicación se aloja en un servidor externo si presenta requisitos de seguridad, utiliza la infraestructura del servidor o necesita integración de datos o administración central. Las aplicaciones web alojadas de forma remota pueden ser SPA, pero no tienen que serlo. Puede modificar una aplicación web existente para que se presente como una vista web o crear específicamente una aplicación web para una aptitud.
- En tiempo de ejecución, el componente de vista web envía al servicio de intermediario una solicitud POST que incluye la URL de llamada de la aptitud y los parámetros de entrada del usuario como una matriz de pares clave-valor. El componente agrega la variable
webview.onDonecomo clave de URL de devolución de llamada. Las claves son los nombres de los parámetros a los que se hace referencia tanto en la propiedad Entradas para servicio de la vista web como en la propiedadwebview.onDone.{ "parameters": [{ "value": "CDG", "key": "origin" }, { "value": "MUC", "key": "destination" }, { "value": "https://<url>:443/connectors/v2/callback?state=cb5443. ..2c" "key": "webview.onDone" }] - El servicio de intermediario devuelve un objeto JSON a la aptitud que tiene una sola propiedad,
webview.url. Su cadena define el URL de redirección en la aplicación web, que utiliza la siguiente solicitud GET de la aptitud. Esta URL también contiene los valores de clave transferidos desde la solicitud POST (a menos que la carga útil de la solicitud POST se guarde en un almacenamiento accesible para la aplicación web). Podría tener un aspecto similar a este:
La aplicación web utiliza la URL de devolución de llamada en una llamada para devolver el control a la aptitud y, opcionalmente, para transferir una carga útil de respuesta.{ "webview.url": "https://<app url>?callbackURL=https://example.com:443/connectors/v2/callback?state=cb55435552c&origin=CDG&destination=MUC }
Esto ilustra el uso del método JQueryself.buttonClick = function (event) { if (event.currentTarget.id === 'Submit') { let data = {}; data.origin = self.origin(); data.destination = self.destination(); //return date in milliseconds data.departureDate = (new Date(self.departureDate())).getTime(); data.returnDate = (new Date(self.returnDate())).getTime(); data.status = "success" /* function jqueryPost(url, data) { return $.ajax({ contentType: "text/plain", url: url, data: data || {}, type: "POST", dataType: "text/plain" }); }; jqueryPost(webViewCallback, JSON.stringify(data)); */ //JQuery post call $.post(webViewCallback,JSON.stringify(data)); } else { //if user pressed "cancel" pass no data but a status informing the bot designer let data = {}; data.status = "cancel" $.post(webViewCallback, JSON.stringify(data)); }$.postpara devolver el objeto JSON a la aptitud con pares de clave-valororigin,destination,departureDateyreturnDate:{ "origin":"CDC" "destination":"MUC" "departureDate":"15689736000000" "returnDate":"15689736000000" }Consejo:
Este fragmento tiene una propiedad"status"definida en"success"o"cancel"para indicar que un usuario ha completado el trabajo en la aplicación web o lo ha cancelado. Los usuarios pueden cerrar el explorador antes de que finalice la solicitud de devolución de llamada, por lo que deben incluir un listener para el cierre que emita una devolución de llamada si aún no se ha producido. La llamada podría usar el estado"cancel"para indicar que el formulario no se completó correctamente. Si el usuario cierra la ventana y no la captura, la aptitud espera hasta que se agote el tiempo de espera. - La aptitud inicia la aplicación web enviando una solicitud GET al URL definido por la propiedad
webview.url. - Después de que la vista web procese la entrada, envía una devolución de llamada de finalización, una solicitud POST, a la URL de devolución de llamada que el componente de vista web ha generado y proporcionado al servicio de intermediario. Esta solicitud no solo señala que la aplicación ha finalizado (y que la aptitud debe reanudar el control de la sesión), sino que puede devolver una carga útil de datos que se almacena en la propiedad Salida para servicio de la vista web.
En función de la estrategia de alojamiento, hay algunos aspectos que conviene recordar:
- Si aloja la aplicación web y el servicio de intermediario en el mismo servidor web, los parámetros de solicitud de la aptitud se pueden guardar en una sesión, con lo que se elimina la necesidad de una cadena de URL larga.
- Si aloja la aplicación web y el servicio de intermediario en diferentes servidores, todos los parámetros de solicitud de la aplicación web de la dirección URL de redirección que se envía a la aptitud se deben codificar como parámetros de consulta.
Creación de un servicio de vista web
Al configurar un servicio de vista web, se conecta la aptitud con el servicio que aloja la aplicación de vista web.
Puede crear servicios de vista web desde la página de vista web, a la que se accede haciendo clic en Componentes (
) en la barra de navegación izquierda y, a continuación, en Vista web. Esta página muestra los distintos servicios de vista web a los que se puede hacer referencia en la propiedad de servicio de componente de vista web.
No es necesario que reconfigure un servicio alojado en Digital Assistant si versiona o clona una aptitud. Sin embargo, si la aplicación web se aloja de forma externa, tiene que volver a configurar el servicio al versionar o clonar la aptitud.
Creación de un servicio de vista web alojado en Digital Assistant
Si bien es posible que necesite proporcionar credenciales de autenticación como parte de la configuración de un servicio de vista web alojado de forma externa, la aplicación web solo se tiene que empaquetar en un archivo TAR (un archivo TGZ) para, a continuación, cargarla. El archivo index.html debe estar en el nivel raíz de este archivo.
tar -zcvf webapp.tgz *En este ejemplo, el comando -zcvf crea un archivo denominado webapp.tgz. Como se indica en Definición de marcadores de posición en el archivo index.html, puede crear la aplicación web utilizando el marco que prefiera, siempre que el archivo index.html se encuentre en el nivel raíz del archivo TGZ. De hecho, index.html puede incluso ser el único archivo del nivel raíz.
- Introduzca el nombre de los servicios en el archivo Name y una descripción (opcional). El nombre introducido aquí debe coincidir con el valor de la propiedad Servicio de componentes de vista web del componente de vista web.
- Active la opción Servicio alojado.
- Suelte el archivo TGZ en el campo Archivo de paquete o busque el archivo TGZ y selecciónelo.
- Haga clic en Crear.
Empaquetado de aplicaciones de Oracle Visual Builder
Puede crear y optimizar las aplicaciones de Oracle Visual Builder para Digital Assistant mediante la tarea vb-build de Grunt. Puede ejecutar esta tarea de forma local o como parte de una compilación en Oracle Developer Cloud Service (DevCS).
- Asegúrese de haber configurado la conexión de servicio para ajustarse a las limitaciones descritas en Integración de una vista web en una aptitud, seleccionando Directo (no usar el proxy) y Permitir acceso anónimo en Oracle Visual Builder.
- Si utiliza Oracle Visual Builder para optimizar el binario, seleccione Transferir a Git. De lo contrario, puede omitir este paso.
Consulte la documentación de Oracle Visual Builder para obtener más información sobre cómo proteger la aplicación de Oracle Visual Builder y cómo integrarla en un repositorio de Git.
Empaquetado de la aplicación de Oracle Visual Builder de forma local
Para optimizar y empaquetar la aplicación de Oracle Visual Builder de forma local:
- En la página inicial de Oracle Visual Builder, seleccione la aplicación y, a continuación, haga clic en Exportar sin datos.
- Descomprima la aplicación.
- Ejecute
npm installen la carpeta raíz (donde se encuentran los archivospackage.jsonyGruntfile.js).Al ejecutar
npm install, se recupera el paquetegrunt-vb-build npm, definido en el archivopackage.json. - Introduzca los siguientes parámetros:
./node_modules/.bin/grunt vb-build \ --url=${serviceURL} \ --username=${username} \ --password=${password} \ --id=${id} --ver=${ver} \ --ver=<your visual app ID>\ --git-source=<local directory for sources>Parámetro Descripción urlURL de la instancia de Visual Builder. usernameNombre de usuario de la instancia de Visual Builder. passwordContraseña de la instancia de Visual Builder. idID de la aplicación. El ID de la aplicación puede ser igual al nombre de la aplicación, pero el ID de la aplicación debe ser exclusivo en el dominio de identidad. verVersión de la aplicación. gitEspecifica la ubicación de los orígenes (si no están en la carpeta actual). - Una vez terminada la creación, navegue al directorio de la aplicación (situado en el directorio
WebApps). Por ejemplo,build/optimized/webApps/financialDispute. - Ejecute el comando GNU tar (
tar -zcvf webapp.tgz *, por ejemplo).tar -zcvf webapp.tgz *
Empaquetado de la aplicación mediante Oracle Developer Cloud Service
- Configure un trabajo de creación en Oracle Cloud para la aplicación web:
- Asocie el trabajo con Git agregando Git como control de origen (la aplicación web también necesita integrarse con un repositorio de Git).
- Seleccione una plantilla de creación.
- Agregue parámetros de cadena que se transfieran a la creación. Estos parámetros incluyen:
- La versión, el ID y el URL de servicio de la aplicación (que se puede obtener desde la instancia de Oracle Visual Builder)
- El usuario y contraseña (un parámetro de contraseña)
- La optimización, como Uglify2.
- Para los pasos de creación, agregue un script de shell que empiece por
npm instally transfiera los parámetros por defecto a Tareas de Grunt de Visual Builder, comovb-build.npm install ./node_modules/.bin/grunt vb-build \ --url=${URL} \ --username=${username} \ --password=${password} \ --id=${id} --ver=${ver} \ --optimize=${optimize} \ --schema=dev \ - Para la configuración posterior a la creación, configure el archivado seleccionando Archivador de artefactos (seleccionado en el menú Agregar acción posterior a compilación) y, a continuación, introduzca
build*zipen el campo Archivos que archivar.
- Una vez finalizada la creación, descargue el archivo ZIP y, a continuación, extráigalo. El archivo
index.htmlse encuentra en la carpetawebapp(situada en el directoriowebapps). - Empaquete la aplicación en un archivo TGZ (
tar -zcvf webapp.tgz *, por ejemplo).
Creación de un servicio de vista web con alojamiento externo
- Nombre: nombre del servicio remoto.
Nota
El nombre introducido aquí debe coincidir con el valor de la propiedad Servicio de componentes de vista web del componente de vista web. - Desactive el conmutador Servicio alojado.
- URL de aplicación web: punto final base proporcionado por un servidor web que acepta los parámetros de origen como la carga útil en una solicitud HTTP POST. Por ejemplo,
https://example.oracle.com:3001/webviewParams. Introduzca el URL del servicio de intermediario si la aplicación web y el servicio de intermediario se alojan por separado. - Token de autorización: token de autorización que se envía con las solicitudes al URL especificado por la propiedad URL de aplicación web. Esta propiedad tiene el formato
Basic <token>oBearer <token>. Propiedad opcional - Parámetros de consulta: Objeto JSON de cadena cuyos pares clave-valor son parámetros de consulta que se agregan a la solicitud POST. Propiedad opcional.
Referencia a los datos devueltos en el flujo de diálogo
Debido a que los valores devueltos en la carga útil no actualizan ninguno de los valores de variable, no es necesario que los nombres de propiedad de la carga útil de respuesta coincidan con los nombres de variable definidos en la propiedad Entradas para servicio.
Puede acceder a la carga útil devuelta mediante ${variable_property_name.value.Param}.

Descripción de la ilustración tester-variables.png
Consejo:
Los desarrolladores de la aplicación web deben asegurarse de que la carga útil devuelta incluya nombres de propiedad descriptivos.