Webviews
Mit Ihrem Skill können Kunden strukturierte Daten mit einer Webview-App eingeben.
Natürliche Sprachunterhaltungen sind von Natur aus frei fließend. Sie stellen jedoch nicht immer die beste Möglichkeit dar, wie Ihr Skill Informationen von seinen Benutzern erfassen kann. Beispiel: Bei der Eingabe von Kreditkarten- oder Reisepassdetails müssen Benutzer bestimmte Informationen eingeben (und zwar präzise). Um Hilfe bei diesen Aufgaben zu erhalten, kann Ihr Skill eine Webview-Anwendung aufrufen.
Diese Anwendungen ermöglichen nicht nur eine strukturierte Dateneingabe über UI-Elemente wie Formulare, Datumsauswahl, Felder und Wertelisten. Sie können auch die Benutzereingabe validieren und Informationen auf verschiedene Arten erfassen, wie z.B. durch Hochladen von Bildern, Erfassen von Benutzersignaturen oder Scannen von Barcodes. Webview-Anwendungen schützen auch sensible Benutzerdaten wie Kreditkartennummern, weil diese Daten bei der Eingabe in die Anwendung nicht in der Chathistorie angezeigt werden. 
Beschreibung der Abbildung webview-webapp.png
Wie wird eine Webview in einen Skill integriert?
- Einen Webview-Service, der den Skill mit der Webanwendung verbindet, die auf einem externen Webserver oder in Digital Assistant gehostet werden kann.
- Eine Webview-Komponente im Dialogablauf. Diese Komponente fungiert als Gateway zur Webanwendung, indem sie den Webview-Service benennt, die Dialogablaufvariablen auflistet, die auf der Webanwendung basieren, und alle von der Webanwendung zurückgegebenen Werte speichert.
Zur Laufzeit rendert die Komponente eine Schaltfläche, mit der die Webanwendung gestartet wird. Die Webview-Komponente startet die Anwendung als Webview innerhalb des Skills oder in einer separaten Browserregisterkarte, wenn der Skill in einem Webkanal ausgeführt wird.
- Die Webanwendung selbst, die in Digital Assistant oder auf einem Remotewebserver gehostet wird.
Tipp:
Weitere Informationen finden Sie im Beispiel für den Webhook-Starter, das in der SDK-Dokumentation unterhttps://oracle.github.io/bots-node-sdk/beschrieben wird.
Von Digital Assistant gehostete Webviews
index.html), die die Webanwendung startet und entsprechend der Eingabe des Skillbenutzers aktualisiert wird. Wenn die Webview-Komponente die SPA ruft, geschieht Folgendes:
- Die Datei
index.htmlwird geladen und startet die Webanwendung als Webview oder in einer separaten Browserregisterkarte. - Die Webview-Komponente übergibt dann die im Dialogablauf erfassten Parameterwerte zusammen mit der Callback-URL. Unter Der SPA den Zugriff auf die Eingabeparameter und die Callback-URL ermöglichen werden verschiedene Ansätze zur Übergabe dieser Werte erläutert.
- Die Webanwendung stellt eine POST-Anforderung an die Callback-URL, die von der Webview-Komponente generiert wurde. Diese Anforderung signalisiert, dass die Anwendung die Verarbeitung abgeschlossen hat. Wenn die Anwendung Daten zurückgibt, werden sie in diese Anforderung als JSON-Objekt aufgenommen, das in der Eigenschaft
variablegespeichert wird. Sie können diese Daten im Dialogablauf mit${variable_property_name.value.Param}referenzieren.
Sie können die SPA mit unterschiedlichen Frameworks schreiben, wie Oracle Visual Builder, Angular, Oracle JavaScript Extension Toolkit (JET) oder React.js.
Das Backend für Oracle Visual Builder verwaltet REST-Verbindungen und Benutzer (über Oracle Identity Cloud Service) und führt Geschäftsobjekte aus, sodass jede Oracle Visual Builder-Anwendung, die in Digital Assistant gehostet wird, folgende Einschränkungen aufweist:
- Es können keine Geschäftsobjekte verwendet werden.
- Eine Integration mit Oracle Identity Cloud Service ist nicht möglich.
- Der Zugriff auf einen REST-Service mit dem Oracle Visual Builder-Authentifizierungsproxy ist nicht möglich.
Um die Anwendung in Digital Assistant zu hosten, müssen Sie sie in einem TAR-Archiv (einer TGZ-Datei) bündeln. Da es sich um eine SPA handelt, muss sich die Datei index.html im Root-Verzeichnis dieses Package befinden.
Der SPA den Zugriff auf die Eingabeparameter und die Callback-URL ermöglichen
window.webViewParameters (die in dem folgenden Snippet angezeigt wird) zur Laufzeit in das Element <head> der Datei index.html ein. Die Schlüssel/Wert-Paare in der Payload melden der SPA die vom Skill übergebenen Eingabewerte.window.webviewParameters = {
parameters: [
{"key": "variableA", "value": "jsonObjA"},
{"key": "variableB", "value": "jsonObjB"},
...
{"key": "webview.onDone",
"value": "https://host:port/patch"},
]
};
Damit Ihre Anwendung auf diese Objekte zugreifen kann, deklarieren Sie eine window.webviewParameters['parameters']-Variable:let webviewParameters = window.webviewParameters !=null?window.webviewParameters['parameters']:null;
Das zurückgegebene Objekt wird aufgrund des Callbacks in der Eigenschaft Ausgabe für Service der Webansicht gespeichert.
app.js einer React-Anwendung gibt die Funktion den Wert für einen benannten Schlüssel zurück. Wenn dieser nicht gefunden werden kann, wird ein Standardwert festgelegt.
Tipp:
Sie können dieses Snippet in Ihrem eigenen Code verwenden. Sie könnenvar getParam anstelle von this.getParam verwenden.
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;
};Platzhalter in der index.html-Datei definieren
Wenn Sie die SPA in Digital Assistant hosten, müssen Sie keine Platzhalter für die Variablenwerte in der Datei index.html definieren. Solange die Datei index.html über ein Element <head> verfügt, weiß Ihre Webanwendung, welche Werte und welcher Callback erwartet werden.
Einzelnen Platzhalter zum Element <head> hinzufügen
Fügen Sie im Element <head> einen <script>-Block mit dem Platzhalter webview.sourceVariableList ein. Die Webanwendung ersetzt dies durch eine JSON-codierte Zeichenfolge, die die Eingabeparameterdaten und die Callback-URL enthält.
Im folgenden Beispiel lautet der Schlüssel window.wvParams. Sie können einen beliebigen Namen für diesen Schlüssel verwenden, solange Sie ihn mit window. anhängen. Sie müssen den Wert immer als "webview.sourceVariableList" definieren.
<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>
Im Beispiel für den App-Code unten:
- Die
let-Anweisung weistwvParamswebview.sourceVariableListzu. - Die Ausgabewerte werden als JSON-Objekt geparst.
fullnameextrahiert den Namen der Variablen, die für die EigenschaftsourceVariableListin der Webviewkomponente definiert ist (wobeinameder Name der definierten Variablen ist).
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);
...
Mehrere Platzhalter zum Element <head> hinzufügen
Fügen Sie einen <script>-Block mit Platzhaltern für jeden Wert hinzu, der für die SourceVariable-Komponente und die Callback-URL definiert ist. Die Webanwendung gibt die Callback-URL und die Daten für Eingabeparameter als JSON-codierte Zeichenfolge zurück. Da Sie Platzhalter hinzugefügt haben, müssen Sie keine window.webviewParameters['parameters']-Variable deklarieren.
- Er muss den Eingabewerten, die für die Eigenschaft
SourceVariabledefiniert sind, entsprechen. - Er muss an
webview.(Beispiel:webview.keyword) angehängt sein.
webview.onDone lauten. Im folgenden Snippet stimmen beispielsweise webview.keyword, webview.assignee, webview.inventor alle mit sourceVariableList: "assignee, keyword, inventor" überein. Die Callback-URL ist mit webview.onDone definiert. Sie können einen beliebigen Namen für den Callback-Schlüssel festlegen, müssen jedoch den Wert immer als webview.onDone definieren.
Sie können optional globale Variablen festlegen, indem Sie die Schlüssel an "window." anhängen (z.B. window.Keyword im folgenden Snippet).
<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>
Callback-URL mit der Schaltfläche "Fertig" in der Webanwendung verknüpfen
Die von der Webview-Komponente generierte Callback-URL ist aufgrund ihres Statetokens (https://...?state=<callback-state-token>) im Wesentlichen ein Single-Use-Callback. Die Default-Lebenszeit der Callback-Anforderung beträgt zwar eine Stunde, doch wird sie gelöscht, nachdem die Web-App die Callback-Anforderung von der Web-App verarbeitet hat. Da Benutzer danach keine Abfragen mehr an die Webanwendung senden können, sollte diese zu einer Endseite mit einer Schaltfläche "Schließen" wechseln, die mit der Callback-URL verknüpft ist.
Extern gehostete Webviews
Sie hosten eine Anwendung auf einem externen Server, wenn sie Sicherheitsanforderungen besitzt, serverseitige Infrastruktur nutzt oder eine Datenintegration oder zentrale Administration erfordert. Bei remote gehosteten Webanwendungen kann es sich um SPAs handeln, dies ist jedoch nicht zwingend der Fall. Sie können eine vorhandene Webanwendung so ändern, dass sie als Webview gerendert wird, oder eine Webanwendung speziell für einen Skill erstellen.
- Zur Laufzeit sendet die Webview-Komponente dem Zwischenservice eine POST-Anforderung, die den Callback-URL des Skills und die Eingabeparameter des Benutzers als Array von Schlüssel/Wert-Paaren enthält. Die Komponente fügt die Variable
webview.onDoneals Callback-URL-Schlüssel hinzu. Die Schlüssel sind die Namen von Parametern, die sowohl von der Eigenschaft Eingabe für Service der Webview als auch von der Eigenschaftwebview.onDonereferenziert werden.{ "parameters": [{ "value": "CDG", "key": "origin" }, { "value": "MUC", "key": "destination" }, { "value": "https://<url>:443/connectors/v2/callback?state=cb5443. ..2c" "key": "webview.onDone" }] - Der Zwischenservice sendet ein JSON-Objekt mit einer einzelnen Eigenschaft (
webview.url) an den Skill zurück. Die zugehörige Zeichenfolge definiert die Umleitungs-URL zur Webanwendung, die von der nachfolgenden GET-Anforderung aus dem Skill verwendet wird. Diese URL enthält auch die Schlüsselwerte, die von der POST-Anforderung übergeben wurden (es sei denn, die Payload der POST-Anforderung wird in einem Speicher gespeichert, auf den die Webanwendung zugreifen kann). Sie könnte wie folgt aussehen:
Die Webanwendung verwendet die Callback-URL in einem Aufruf, um die Kontrolle an den Skill zurückzugeben, und optional, um eine Antwort-Payload zu übergeben.{ "webview.url": "https://<app url>?callbackURL=https://example.com:443/connectors/v2/callback?state=cb55435552c&origin=CDG&destination=MUC }
Dies veranschaulicht die Verwendung der Methode 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, um ein JSON-Objekt mit Schlüsselwertpaarenorigin,destination,departureDateundreturnDatean den Skill zurückzugeben:{ "origin":"CDC" "destination":"MUC" "departureDate":"15689736000000" "returnDate":"15689736000000" }Tipp:
Dieses Snippet weist eine Eigenschaft"status"auf, die auf"success"oder"cancel"gesetzt ist, um anzugeben, dass ein Benutzer die Arbeit in der Webanwendung abgeschlossen oder abgebrochen hat. Benutzer können den Browser schließen, bevor die Rückrufanforderung abgeschlossen ist. Nehmen Sie daher einen Listener für das Schließen auf, der einen Rückruf ausgibt, falls noch nicht geschehen. Der Aufruf könnte den Status"cancel"verwenden, um anzugeben, dass das Formular nicht erfolgreich abgeschlossen wurde. Wenn der Benutzer das Fenster schließt und Sie dies nicht abfangen, wartet der Skill bis zum Timeout. - Der Skill startet die Webanwendung durch Senden einer GET-Anforderung an die URL, die durch die Eigenschaft
webview.urldefiniert wird. - Nachdem die Webview die Eingabe verarbeitet hat, sendet sie einen Abschluss-Rückruf (eine POST-Anforderung) an die Rückruf-URL, die von der Webview-Komponente generiert und für den Zwischenservice bereitgestellt wurde. Diese Anforderung signalisiert nicht nur, dass die Anwendung beendet wurde (und der Skill die Kontrolle der Session fortsetzen muss), sondern kann auch eine Daten-Payload zurückgeben, die in der Eigenschaft Ausgabe für Service der Webansicht gespeichert wird.
Je nach Hostingstrategie gibt es verschiedene Aspekte, die Sie beachten sollten:
- Wenn Sie die Webanwendung und den Zwischenservice auf demselben Webserver hosten, können die Anforderungsparameter des Skills in einer Session gespeichert werden, sodass keine lange URL-Zeichenfolge erforderlich ist.
- Wenn Sie die Webanwendung und den Zwischenservice auf verschiedenen Servern hosten, müssen alle Webanwendungsanfrageparameter in der Umleitungs-URL, die an den Skill gesendet werden, als Abfrageparameter codiert werden.
Webview-Service erstellen
Durch die Konfiguration eines Webview-Service wird Ihr Skill mit dem Service verbunden, der die Webview-Anwendung hostet.
Sie erstellen Webview-Services auf der Seite "Webview", auf die Sie zugreifen, indem Sie zuerst in der linken Navigationsleiste auf Komponenten (
) und dann auf Webview klicken. Auf dieser Seite werden die verschiedenen Webview-Services aufgeführt, die Sie in der Webview-Komponentenserviceeigenschaft von Webview referenzieren können.
Sie müssen einen von Digital Assistant gehosteten Service nicht neu konfigurieren, wenn Sie Ihren Skill versionieren oder kopieren. Wenn Sie die Webanwendung extern hosten, müssen Sie den Service jedoch neu konfigurieren, wenn Sie Ihren Skill versionieren oder klonen.
Von Digital Assistant gehosteten Webview-Service erstellen
Möglicherweise müssen Sie im Rahmen der Konfiguration eines extern gehosteten Webview-Service Authentifizierungszugangsdaten angeben. Sie müssen die Webanwendung jedoch nur in ein TAR-Archiv (eine TGZ-Datei) einbinden und sie dann hochladen. Die Datei index.html muss sich auf der Root-Ebene dieser Datei befinden.
tar -zcvf webapp.tgz *In diesem Beispiel erstellt der Befehl -zcvf eine Datei mit dem Namen webapp.tgz. Wie unter Platzhalter in der index.html-Datei definieren angegeben, können Sie die Webanwendung mit dem Framework Ihrer Wahl erstellen, solange die Datei index.html im Root-Verzeichnis der TGZ-Datei gespeichert ist. Die index.html-Datei kann sogar die einzige Datei auf Root-Ebene sein.
- Geben Sie den Namen der Services und eine Beschreibung (optional) in die Datei "Name" ein. Der Name, den Sie hier eingeben, muss mit dem Wert für die Eigenschaft Webview-Komponentenservice der Webview-Komponente übereinstimmen.
- Aktivieren Sie die Option Von Service gehostet.
- Legen Sie die TGZ-Datei im Feld "Packagedatei" ab, oder navigieren Sie zu der TGZ-Datei, und wählen Sie diese aus.
- Klicken Sie auf Erstellen.
Oracle Visual Builder-Anwendungen in Packages integrieren
Sie erstellen und optimieren Ihre Oracle Visual Builder-Anwendungen für Digital Assistant mit der Grunt-Aufgabe vb-build. Sie können diese Aufgabe lokal oder als Teil eines Builds in Oracle Developer Cloud Service (DevCS) ausführen.
- Stellen Sie sicher, dass Sie die zugehörige Serviceverbindung so konfiguriert haben, dass die unter Wie wird eine Webview in einen Skill integriert? beschriebenen Einschränkungen berücksichtigt werden. Wählen Sie dazu in Oracle Visual Builder die Optionen Direkt (Proxy umgehen) und Anonymen Zugriff zulassen aus.
- Wenn Sie in Oracle Visual Builder die Binärdatei optimieren, wählen Sie An Git übergeben aus. Andernfalls können Sie diesen Schritt überspringen.
In der Oracle Visual Builder-Dokumentation finden Sie weitere Informationen, wie Sie die Oracle Visual Builder-Anwendung sichern und in ein Git-Repository integrieren können.
Oracle Visual Builder-Anwendung lokal in ein Package integrieren
So können Sie Ihre Oracle Visual Builder-Anwendung lokal optimieren und in ein Package integrieren:
- Wählen Sie auf der Oracle Visual Builder-Homepage die Anwendung aus, und klicken Sie auf Ohne Daten exportieren.
- Dekomprimieren Sie die Anwendung.
- Führen Sie
npm installim Root-Ordner aus (in dem sowohl diepackage.json- als auch dieGruntfile.js-Datei gespeichert ist).Durch Ausführen von
npm installwird das Packagegrunt-vb-build npmabgerufen, das in der Dateipackage.jsondefiniert ist. - Geben Sie die folgenden Parameter ein:
./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>Parameter Beschreibung urlDie URL Ihrer Visual Builder-Instanz. usernameIhr Benutzername für die Visual Builder-Instanz. passwordIhr Kennwort für die Visual Builder-Instanz. idDie ID der Anwendung. Die Anwendungs-ID kann mit dem Anwendungsnamen identisch sein, die Anwendungs-ID muss jedoch in Ihrer Identitätsdomain eindeutig sein. verDie Version Ihrer Anwendung. gitGibt den Speicherort der Quellen an (wenn diese sich nicht im aktuellen Ordner befinden). - Navigieren Sie nach Abschluss des Builds zum Anwendungsverzeichnis (im Verzeichnis
WebApps). Beispiel:build/optimized/webApps/financialDispute. - Führen Sie den GNU-Befehl "tar" aus (Beispiel:
tar -zcvf webapp.tgz *).tar -zcvf webapp.tgz *
Anwendung mit Oracle Developer Cloud Service in ein Package integrieren
- Konfigurieren Sie einen Build-Job in Oracle Cloud für die Webanwendung:
- Verknüpfen Sie den Job mit Git, indem Sie Git als Versionskontrolle hinzufügen (die Webanwendung muss auch in ein Git-Repository integriert werden).
- Wählen Sie eine Build-Vorlage aus.
- Fügen Sie Zeichenfolgenparameter hinzu, die an den Build übergeben werden. Diese Parameter umfassen:
- Service-URL, ID und Version der Anwendung (die Sie von der Oracle Visual Builder-Instanz abrufen können)
- Ihr Benutzername und Ihr Kennwort (ein Kennwortparameter)
- Die Optimierung (Beispiel: Uglify2)
- Fügen Sie für die Build-Schritte ein Shell-Skript hinzu, das mit
npm installbeginnt und die Standardparameter an die Grunt-Aufgaben von Visual Builder übergibt (Beispiel:vb-build).npm install ./node_modules/.bin/grunt vb-build \ --url=${URL} \ --username=${username} \ --password=${password} \ --id=${id} --ver=${ver} \ --optimize=${optimize} \ --schema=dev \ - Konfigurieren Sie für die Konfiguration "Nach Erstellung" eine Archivierung, indem Sie die Option Artefakt-Archiver auswählen (im Menü "Aktion nach Erstellung hinzufügen"). Geben Sie dann in das Feld "Zu archivierende Dateien"
build*zipein.
- Laden Sie nach Abschluss des Builds die ZIP-Datei herunter, und extrahieren Sie sie. Die Datei
index.htmlbefindet sich im Ordnerwebapp(im Verzeichniswebapps). - Verpacken Sie die Anwendung in eine TGZ-Datei (Beispiel:
tar -zcvf webapp.tgz *).
Extern gehosteten Webview-Service erstellen
- Name: Der Name für den Remoteservice.
Hinweis
Der Name, den Sie hier eingeben, muss mit dem Wert für die Eigenschaft Webview-Komponentenservice der Webview-Komponente übereinstimmen. - Deaktivieren Sie die Option Von Service gehostet.
- Webanwendungs-URL: Der von einem Webserver bereitgestellte Basisendpunkt, der die Quellparameter als Payload in einer HTTP-POST-Anforderung akzeptiert. Beispiel:
https://example.oracle.com:3001/webviewParams. Geben Sie die URL für den Zwischenservice ein, wenn die Webanwendung und der Zwischenservice separat gehostet werden. - Authentifizierungstoken: Ein Autorisierungstoken, das mit Anforderungen an die URL gesendet wird, die von der Eigenschaft Webanwendungs-URL angegeben wird. Diese Eigenschaft weist das Format
Basic <token>oderBearer <token>auf. Dies ist eine optionale Eigenschaft - Abfrageparameter: Ein ins Zeichenfolgenformat konvertiertes JSON-Objekt, dessen Schlüssel/Wert-Paare die Abfrageparameter sind, die an die POST-Anforderung angehängt werden. Dies ist eine optionale Eigenschaft.
Zurückgegebene Daten im Dialogablauf referenzieren
Da die in der Payload zurückgegebenen Werte keinen der Variablenwerte aktualisieren, müssen die Eigenschaftsnamen in der Antwort-Payload nicht mit den in der Eigenschaft Eingaben für Service definierten Variablennamen übereinstimmen.
Sie können mit ${variable_property_name.value.Param} auf die zurückgegebene Payload zugreifen.

Beschreibung des Illustrationstests-variables.png
Tipp:
Entwickler von Webanwendungen müssen sicherstellen, dass die zurückgegebene Payload aussagekräftige Eigenschaftsnamen enthält.