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.
Description de l'image webview_webapp.png ci-après

Comment intégrer une vue Web à une brique ?

Pour intégrer une application Web à votre brique, vous avez besoin des éléments suivants :
  • 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'adresse https://oracle.github.io/bots-node-sdk/.

Vues Web hébergées par Digital Assistant

Les applications Web hébergées dans Digital Assistant doivent être des applications à page unique, à savoir des applications Web côté client comportant une seule page HTML (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 :
  1. Le fichier index.html est chargé et lance l'application Web en tant que vue Web ou dans un onglet de navigateur distinct.
  2. 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.
  3. 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.

Remarque

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.
Par conséquent, si vous prenez en charge l'une de ces fonctionnalités, vous devez héberger l'application Oracle Visual Builder sur un serveur externe.

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

Lorsque vous hébergez une application à page unique dans Digital Assistant, le composant de vue Web injecte la variable 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.
Dans le fragment de code suivant du fichier 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 utiliser var 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 affecte webview.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'].

Comme illustré dans le fragment de code suivant, les espaces réservés sont définis par paires clé-valeur. Chaque valeur doit remplir les conditions suivantes :
  • Correspondre aux valeurs d'entrée définies pour la propriété SourceVariable.
  • Etre précédée de webview. (par exemple, webview.keyword).
En outre, la valeur de callback doit être 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.

Pour les applications Web hébergées en externe, vous devez héberger l'application Web elle-même ainsi qu'un service intermédiaire. L'application Web attend une demande GET de la brique, tandis que le service intermédiaire reçoit les demandes POST de la brique et formule l'URL de réacheminement vers l'application Web. Tous deux peuvent résider sur le même serveur Web ou être hébergés sur des serveurs Web distincts. Quelle que soit l'implémentation choisie, le flux de demande se présente comme suit :
  1. 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" 
    }]
    
  2. 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 :
    {
    "webview.url":
            "https://<app url>?callbackURL=https://example.com:443/connectors/v2/callback?state=cb55435552c&origin=CDG&destination=MUC
    }
    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.
    self.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));          
            }
    Cette capture d'écran illustre l'utilisation de la méthode JQuery $.post pour renvoyer l'objet JSON à la brique avec les paires clé-valeur origin, destination, departureDate et returnDate :
    {
    "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.
  3. La brique lance l'application Web en envoyant une demande GET à l'URL définie par la propriété webview.url.
  4. 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 (Il s'agit d'une image de l'icône 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.

Remarque

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.

Vous pouvez packager l'application à l'aide de la commande GNU tar :
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.
Pour créer le service, procédez comme suit :
  1. 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.
  2. Activez l'option Service hébergé.
  3. Déplacez le fichier TGZ dans le champ Fichier de package ou accédez au fichier TGZ et sélectionnez-le.
  4. 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.

Avant de créer l'application Oracle Visual Builder, effectuez les opérations suivantes :
  • 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 :

  1. Sur la page d'accueil d'Oracle Visual Builder, sélectionnez votre application, puis cliquez sur Exporter sans données.
  2. Décompressez l'application.
  3. Exécutez npm install sur le dossier racine (où se trouvent les fichiers package.json et Gruntfile.js).

    L'exécution de npm install extrait le package grunt-vb-build npm défini dans le fichier package.json.

  4. 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).
  5. 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.
  6. 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

Pour créer et optimiser l'application dans Oracle Developer Cloud Service, procédez comme suit :
  1. 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 que vb-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.
  2. 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 dossier webapp (situé dans le répertoire webapps).
  3. 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

Pour les applications Web hébergées sur des serveurs d'applications Web externes, indiquez les éléments suivants :
  • 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> ou Bearer <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}.

Une fois que vous avez créé le service de vue Web et configuré le composant de vue Web, vous pouvez trouver les données renvoyées par l'application Web à l'aide du testeur de briques (Icône du testeur.). Une fois que votre conversation a passé l'état de vue Web, utilisez la fenêtre Conversation pour examiner les valeurs renvoyées pour les variables.
Description de l'image tester_variables.png ci-après

Conseil :

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