Vues Web
Votre brique peut permettre aux clients d'entrer des données structurées à l'aide d'une application de vue Web.
Les conversations en langage naturel sont par nature très fluides. Cependant, elles ne constituent pas toujours le meilleur moyen pour collecter les informations des utilisateurs. Par exemple, lorsqu'il s'agit d'entrer les détails d'une carte de crédit ou d'un passeport, les utilisateurs doivent entrer des informations spécifiques (et les saisir de façon précise). Pour aider à la réalisation de ces tâches, votre brique peut appeler une application de vue Web.
Ces applications permettent non seulement de saisir des données de façon structurée via des éléments d'interface utilisateur tels que des formulaires, des sélecteurs de date, des champs et des listes de valeurs, mais également de valider la saisie utilisateur et de collecter des informations de diverses manières, comme le téléchargement d'images, la capture de signatures utilisateur ou la lecture de codes-barres. Les applications de vue Web protègent également les données utilisateur sensibles, telles que les numéros de carte de crédit, car ces données n'apparaissent pas dans l'historique de discussion lorsqu'elles sont saisies dans l'application.
Comment intégrer une vue Web à une brique ?
- Service de vue Web reliant la brique à l'application Web qui peut être hébergée sur un serveur Web externe ou dans Digital Assistant.
- Composant de vue Web dans le flux de dialogue. Ce composant agit comme une passerelle vers l'application Web en nommant le service Webview, en répertoriant les variables de flux de dialogue qui sont basées sur l'application Web et en stockant les valeurs renvoyées par l'application Web.
Lors de son exécution, le composant affiche un bouton qui lance l'application Web. Le composant de vue Web lance l'application en tant que vue Web dans la brique, ou dans un onglet de navigateur distinct lorsque la brique est exécutée sur un canal Web.
- Application Web elle-même, hébergée dans Digital Assistant ou sur un serveur Web distant.
Conseil :
Reportez-vous à l'exemple de démarrage de webhook décrit dans la documentation SDK à l'adressehttps://oracle.github.io/bots-node-sdk/
.
Vues Web hébergées par Digital Assistant
index.html
) qui lance l'application Web et qui est mise à jour en réponse à la saisie utilisateur de la brique. Lorsque le composant de vue Web appelle l'application à page unique :
- Le fichier
index.html
est chargé et lance l'application Web en tant que vue Web ou dans un onglet de navigateur distinct. - Le composant de vue Web transmet ensuite les valeurs de paramètre collectées dans le flux de dialogue avec l'URL de callback. Autorisation de l'accès de l'application à page unique aux paramètres d'entrée et à l'URL de callback décrit les différentes approches permettant de transmettre ces valeurs.
- L'application Web envoie une demande POST à l'URL de callback générée par le composant Webview. Cette demande signale que l'application a terminé son traitement. Si l'application renvoie des données, elles sont incluses dans cette demande en tant qu'objet JSON stocké dans la propriété
variable
. Vous pouvez référence ces données dans votre flux de dialogue à l'aide de${variable_property_name.value.Param}
.
Vous pouvez écrire l'application à page unique à l'aide de différentes structures, telles qu'Oracle Visual Builder, Angular, Oracle JavaScript Extension Toolkit ou React.js.
Le back-end d'Oracle Visual Builder gère les connexions REST et les utilisateurs (via Oracle Identity Cloud Service). Il exécute également les business objects, de telle sorte que toute application Oracle Visual Builder hébergée par Digital Assistant présente les limites suivantes :
- Elle ne peut pas utiliser de business objects.
- Elle ne peut pas être intégrée à Oracle Identity Cloud Service.
- Elle ne peut pas accéder à un service REST via le proxy d'authentification Oracle Visual Builder.
Pour héberger l'application dans Digital Assistant, vous devez la compresser dans une archive TAR (fichier TGZ). Comme il s'agit d'une application à page unique, le fichier index.html
doit être à la racine de ce package.
Autorisation de l'accès de l'application à page unique aux paramètres d'entrée et à l'URL de callback
window.webViewParameters
(illustrée dans le fragment de code suivant) dans l'élément <head>
du fichier index.html
lors de l'exécution. Les paires clé-valeur dans la charge utile informent l'application à page unique des valeurs d'entrée transmises par la brique.window.webviewParameters = {
parameters: [
{"key": "variableA", "value": "jsonObjA"},
{"key": "variableB", "value": "jsonObjB"},
...
{"key": "webview.onDone",
"value": "https://host:port/patch"},
]
};
Pour permettre à votre application d'accéder à ces objets, déclarez une variable window.webviewParameters['parameters']
:let webviewParameters = window.webviewParameters !=null?window.webviewParameters['parameters']:null;
L'objet renvoyé est stocké dans la propriété Sortie pour le service de la vue Web à cause du callback.
app.js
d'une application React, la fonction renvoie la valeur d'une clé nommée. Si celle-ci est introuvable, l'application définit une valeur par défaut.
Conseil :
Vous pouvez utiliser ce fragment de code dans votre propre code. Vous pouvez utiliservar getParam
au lieu 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;
};
Définition d'espaces réservés dans le fichier index.html
Lorsque vous hébergez l'application à page unique au sein de Digital Assistant, vous n'avez pas besoin de définir d'espaces réservés pour les valeurs de variable du fichier index.html
. Tant que le fichier index.html
contient un élément <head>
, l'application Web connaît les valeurs attendues et le callback.
Ajout d'un espace réservé unique à l'élément <head>
Dans l'élément <head>
, insérez un bloc <script>
comportant l'espace réservé webview.sourceVariableList
. L'application Web le remplace par une chaîne encodée au format JSON contenant les données de paramètre d'entrée et l'URL de callback.
Dans l'exemple suivant, la clé est window.wvParams
. Vous pouvez utiliser n'importe quel nom pour cette clé, tant que vous ajoutez window.
à la fin. Vous devez toujours définir la valeur sur "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>
Dans l'exemple de code d'application ci-dessous :
- L'instruction
let
affectewebview.sourceVariableList
àwvParams
. - Les valeurs de sortie sont analysées en tant qu'objet JSON.
fullname
extrait le nom de la variable définie pour la propriétésourceVariableList
dans le composant de vue Web (oùname
est le nom de la variable définie).
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);
...
Ajout de plusieurs espaces réservés à l'élément <head>
Ajoutez un bloc <script>
contenant des espaces réservés correspondant à chaque valeur définie pour le composant SourceVariable
et l'URL de callback. L'application Web renvoie l'URL de callback et les données des paramètres d'entrée sous la forme d'une chaîne encodée au format JSON. Si vous ajoutez des espaces réservés, vous n'avez pas besoin de déclarer une variable window.webviewParameters['parameters']
.
- Correspondre aux valeurs d'entrée définies pour la propriété
SourceVariable
. - Etre précédée de
webview.
(par exemple,webview.keyword
).
webview.onDone
. Par exemple, dans l'extrait suivant, webview.keyword
, webview.assignee
et webview.inventor
correspondent tous à sourceVariableList: "assignee, keyword, inventor"
. L'URL de callback est définie sur webview.onDone
. Vous pouvez nommer la clé de callback comme vous voulez, mais vous devez toujours définir sa valeur sur webview.onDone
.
Vous pouvez éventuellement définir des variables globales en ajoutant window. au début des clés (par exemple, window.Keyword
dans le fragment de code suivant).
<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>
Connexion de l'URL de callback à un bouton Terminé dans l'application Web
L'URL de callback générée par le composant Webview est essentiellement un callback à usage unique en raison de son jeton d'état (https://...?state=<callback-state-token>
). Sa durée de vie par défaut est d'une heure, mais elle est effacée une fois que le composant Webview gère la demande de callback de l'application Web. Les utilisateurs ne pouvant pas interroger l'application Web au-delà ce point, vous devez mettre en place une transition vers une page de fin à l'aide d'un bouton Fermer connecté à l'URL de callback.
Vues Web hébergées en externe
Vous devez héberger une application sur un serveur externe lorsqu'elle est soumise à des exigences de sécurité, qu'elle utilise une infrastructure côté serveur, ou qu'elle requiert une intégration de données ou une administration centrale. Les applications Web hébergées à distance peuvent être des applications à page unique, mais pas uniquement. Vous pouvez modifier une application Web existante pour l'afficher comme une vue Web ou créer une application Web propre à une brique.
- Au moment de l'exécution, le composant de vue Web envoie au service intermédiaire une demande POST qui inclut l'URL de callback de la brique et les paramètres de saisie utilisateur sous forme de tableau de paires clé-valeur. Le composant ajoute la variable
webview.onDone
en tant que clé d'URL de callback. Les clés sont les noms des paramètres référencés à la fois par la propriété Entrées pour le service de la vue Web et par la propriétéwebview.onDone
.{ "parameters": [{ "value": "CDG", "key": "origin" }, { "value": "MUC", "key": "destination" }, { "value": "https://<url>:443/connectors/v2/callback?state=cb5443. ..2c" "key": "webview.onDone" }]
- Le service intermédiaire renvoie un objet JSON à la brique qui comporte une seule propriété :
webview.url
. Sa chaîne définit l'URL de réacheminement vers l'application Web qui est utilisée par la demande GET envoyée ensuite par la brique. Cette URL contient également les valeurs de clé transmises par la demande POST (sauf si la charge utile de la demande POST est enregistrée dans un stockage accessible à l'application Web). Elle peut se présenter comme suit :
L'application Web utilise l'URL de rappel dans un appel pour retransmettre le contrôle à la brique et, éventuellement, pour transmettre une charge utile de réponse.{ "webview.url": "https://<app url>?callbackURL=https://example.com:443/connectors/v2/callback?state=cb55435552c&origin=CDG&destination=MUC }
Cette capture d'écran illustre l'utilisation de la méthode 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)); }
$.post
pour renvoyer l'objet JSON à la brique avec les paires clé-valeurorigin
,destination
,departureDate
etreturnDate
:{ "origin":"CDC" "destination":"MUC" "departureDate":"15689736000000" "returnDate":"15689736000000" }
Conseil :
Ce fragment de code possède une propriété"status"
définie sur"success"
ou"cancel"
pour indiquer qu'un utilisateur a terminé son travail dans l'application Web ou l'a annulé. Les utilisateurs peuvent fermer le navigateur avant la fin de la demande de rappel. Incluez donc un processus d'écoute pour la fermeture qui émet un rappel si ce n'est pas encore le cas. L'appel peut utiliser le statut"cancel"
pour indiquer que le formulaire n'a pas été rempli avec succès. Si l'utilisateur ferme la fenêtre et que vous ne l'attrapez pas, la brique attend son expiration. - La brique lance l'application Web en envoyant une demande GET à l'URL définie par la propriété
webview.url
. - Une fois que la vue Web a traité l'entrée, elle envoie un rappel d'achèvement, c'est-à-dire une demande POST, à l'URL de rappel générée par le composant de vue Web et fournie au service intermédiaire. Cette demande indique non seulement que l'application est terminée (et que la brique doit reprendre le contrôle de la session), mais elle peut renvoyer une charge utile de données, qui est stockée dans la propriété Sortie pour le service de la vue Web.
En fonction de votre stratégie d'hébergement, vous devez tenir compte des éléments suivants :
- Si vous hébergez l'application Web et le service intermédiaire sur le même serveur Web, les paramètres de demande de la brique peuvent être enregistrés dans une session. Vous n'avez alors pas besoin d'une longue chaîne d'URL.
- Si vous hébergez l'application Web et le service intermédiaire sur des serveurs différents, tous les paramètres de demande de l'application Web dans l'URL de réacheminement envoyée à la brique doivent être encodés en tant que paramètres de requête.
Création d'un service de vue Web
La configuration d'un service de vue Web vous permet de relier votre brique au service hébergeant l'application de vue Web.
Vous pouvez créer des services de vue Web à partir de la page Vue Web, à laquelle vous pouvez accéder en cliquant sur Composants () dans la barre de navigation de gauche, puis sur Vue Web. Cette page répertorie les différents services de vue Web que vous pouvez référencer dans la propriété Service de composant de vue Web de la vue Web.
Vous n'avez pas besoin de reconfigurer un service hébergé par Digital Assistant lorsque vous créez une version de votre brique ou que vous la clonez. Toutefois, si vous hébergez l'application Web en externe, vous devez reconfigurer le service lorsque vous créez une autre version de votre brique ou que vous la clonez.
Création d'un service de vue Web hébergé par Digital Assistant
Vous devrez peut-être fournir des informations d'identification d'authentification lors de la configuration d'un service de vue Web hébergé en externe, mais vous pouvez simplement packager l'application Web dans une archive TAR (fichier TGZ) et la télécharger. Le fichier index.html
doit se situer au niveau racine de ce fichier.
tar -zcvf webapp.tgz *
Dans cet exemple, la commande -zcvf
crée un fichier nommé webapp.tgz
. Comme indiqué dans Définition d'espaces réservés dans le fichier index.html, vous pouvez créer l'application Web en utilisant la structure de votre choix du moment que le fichier index.html
est situé à la racine du fichier TGZ. De fait, index.html
peut même être le seul fichier situé au niveau racine.
- Nommez les services dans le fichier de nom et saisissez une description (facultative). Le nom que vous saisissez ici doit correspondre à la valeur de la propriété Service de composant de vue Web du composant de vue Web.
- Activez l'option Service hébergé.
- Déplacez le fichier TGZ dans le champ Fichier de package ou accédez au fichier TGZ et sélectionnez-le.
- Cliquez sur Créer.
Mise en package des applications Oracle Visual Builder
Vous pouvez créer et optimiser vos applications Oracle Visual Builder pour Digital Assistant à l'aide de la tâche Grunt vb-build Vous pouvez exécuter cette tâche localement ou dans le cadre d'un build sur Oracle Developer Cloud Service.
- Assurez-vous que vous avez configuré sa connexion de service de façon à prendre en compte les restrictions décrites dans Comment intégrer une vue Web à une brique ? en sélectionnant Direct (contourner le proxy) et Autoriser l'accès anonyme dans Oracle Visual Builder.
- Si vous utilisez Oracle Visual Builder pour optimiser le fichier binaire, sélectionnez Propager vers Git. Sinon, vous pouvez ignorer cette étape.
Reportez-vous à la documentation Oracle Visual Builder pour en savoir plus sur la sécurisation de l'application Oracle Visual Builder et sur son intégration à un référentiel Git.
Mise en package de l'application Oracle Visual Builder en local
Pour optimiser et packager votre application Oracle Visual Builder en local, procédez comme suit :
- Sur la page d'accueil d'Oracle Visual Builder, sélectionnez votre application, puis cliquez sur Exporter sans données.
- Décompressez l'application.
- Exécutez
npm install
sur le dossier racine (où se trouvent les fichierspackage.json
etGruntfile.js
).L'exécution de
npm install
extrait le packagegrunt-vb-build npm
défini dans le fichierpackage.json
. - Entrez les paramètres suivants :
./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>
Paramètre Description url
URL de votre instance Visual Builder. username
Nom utilisateur pour l'instance Visual Builder. password
Mot de passe pour l'instance Visual Builder. id
ID de l'application. L'ID d'application peut être identique au nom d'application, mais il doit être unique dans votre domaine d'identité. ver
Version de votre application. git
Indique l'emplacement des sources (si elles ne se trouvent pas dans le dossier en cours). - Une fois le build terminé, accédez au répertoire de l'application (situé dans le répertoire
WebApps
). Par exemple,build/optimized/webApps/financialDispute
. - Exécutez la commande GNU tar (par exemple,
tar -zcvf webapp.tgz *
).tar -zcvf webapp.tgz *
Mise en package de l'application à l'aide d'Oracle Developer Cloud Service
- Configurez un travail de build dans Oracle Cloud pour l'application Web :
- Associez le travail à Git en ajoutant Git en tant que contrôle des versions (l'application Web doit également être intégrée à un référentiel Git).
- Sélectionnez le modèle de build.
- Ajoutez des paramètres de chaîne à transmettre au build. Ce sont les paramètres suivants :
- URL de service, ID et version de l'application (que vous pouvez obtenir à partir de votre instance Oracle Visual Builder)
- Utilisateur et mot de passe (paramètre de mot de passe)
- Optimisation, par exemple Uglify2.
- Pour les étapes de construction, ajoutez un script shell qui commence par
npm install
et qui transmet les paramètres par défaut aux tâches Grunt Visual Builder, telles quevb-build
.npm install ./node_modules/.bin/grunt vb-build \ --url=${URL} \ --username=${username} \ --password=${password} \ --id=${id} --ver=${ver} \ --optimize=${optimize} \ --schema=dev \
- Pour la configuration Après construction, configurez l'archivage en sélectionnant Processus d'archivage d'artefacts (sélectionné dans le menu Ajouter une action Après construction), puis entrez
build*zip
dans le champ Fichiers à archiver.
- Une fois la compilation terminée, téléchargez le fichier ZIP et procédez à son extraction. Le fichier
index.html
se trouve dans le dossierwebapp
(situé dans le répertoirewebapps
). - Packagez l'application dans un fichier TGZ (par exemple,
tar -zcvf webapp.tgz *
).
Création d'un service de vue Web hébergé en externe
- Nom : nom du service distant.
Remarque
Le nom que vous saisissez ici doit correspondre à la valeur de la propriété Service de composant de vue Web du composant de vue Web. - Désactivez l'option Service hébergé.
- URL d'application Web : adresse de base fournie par un serveur Web qui accepte les paramètres source comme charge utile dans une demande HTTP POST. Par exemple,
https://example.oracle.com:3001/webviewParams
. Entrez l'URL du service intermédiaire lorsque l'application Web et le service intermédiaire sont hébergés séparément. - Jeton d'authentification : jeton d'authentification envoyé avec les demandes à l'URL indiquée par la propriété URL d'application Web. Cette propriété se présente sous la forme
Basic <token>
ouBearer <token>
. Il s'agit d'une propriété facultative - Paramètres de requête : objet JSON présenté sous forme de chaîne dont les paires clé-valeur sont les paramètres de requête ajoutés au début de la demande POST. Il s'agit d'une propriété facultative.
Référencement des données renvoyées dans le flux de dialogue
Etant donné que les valeurs renvoyées dans la charge utile ne mettent pas à jour les valeurs de variable, les noms de propriété dans la charge utile de réponse ne doivent pas nécessairement correspondre aux noms de variable définis dans la propriété Entrées pour le service.
Vous pouvez accéder à la charge utile renvoyée à l'aide de ${variable_property_name.value.Param}
.


Conseil :
Les développeurs d'application Web doivent s'assurer que la charge utile renvoyée comprend des noms de propriété descriptifs.