Webビュー
スキルにより、顧客はWebビュー・アプリケーションを使用して構造化データを入力できるようになります。
自然言語での会話は、その性質上、自由に流れるものです。ただし、ユーザーから情報を収集するスキルには、必ずしも最適な方法ではない場合があります。たとえば、クレジット・カードやパスポートの詳細を入力する際には、ユーザーは特定の情報を(正確に)入力する必要があります。このような種類のタスクをサポートするために、スキルでWebビュー・アプリケーションをコールできます。
これらのアプリケーションは、フォーム、日付ピッカー、フィールド、LOVなどのUI要素を介した構造化データの入力を可能にするだけでなく、ユーザー入力を検証し、イメージのアップロード、ユーザー署名の取得、バーコードのスキャンなど、様々な方法で情報を収集することもできます。クレジット・カード番号などの機密ユーザー・データはアプリケーションに入力された際にチャット履歴に表示されないため、Webビュー・アプリケーションはこのデータも保護します。
図webview-webapp.pngの説明
Webビューをスキルに統合する方法
- 外部Webサーバーやデジタル・アシスタント内でホストできるWebアプリケーションにスキルを接続するWebビュー・サービス。
- ダイアログ・フローのWebビュー・コンポーネント。このコンポーネントは、Webビュー・サービスに名前を付け、Webアプリケーションに基づいて取得されるダイアログ・フロー変数をリストし、Webアプリケーションによって返される値を格納することで、Webアプリケーションへのゲートウェイとして機能します。
実行時、このコンポーネントはWebアプリケーションを起動するボタンをレンダリングします。Webビュー・コンポーネントは、スキル内のWebビューとして、またはWebチャネルでスキルが実行される場合は別のブラウザ・タブで、アプリケーションを起動します。
- デジタル・アシスタント内、またはリモートWebサーバー上でホストされるWebアプリケーション自体。
ヒント:
SDKのドキュメント(https://oracle.github.io/bots-node-sdk/
)に記載されているWebフック・スタータのサンプルを参照してください。
デジタル・アシスタントでホストされるWebビュー
index.html
)を持つクライアント側Webアプリケーションである必要があります。Webビュー・コンポーネントがSPAをコールすると:
index.html
がロードされ、WebアプリケーションがWebビューとして、または別のブラウザ・タブで起動されます。- Webビュー・コンポーネントは、ダイアログ・フローで収集されたパラメータ値をコールバックURLとともに渡します。SPAが入力パラメータおよびコールバックURLにアクセスできるようにするでは、これらの値を渡す様々な方法を説明しています。
- Webアプリケーションは、Webビュー・コンポーネントによって生成されたコールバックURLへのPOSTリクエストを行います。このリクエストは、アプリケーションが処理を完了したことを示します。アプリケーションがデータを返す場合、データは
variable
プロパティに格納されるJSONオブジェクトとしてこのリクエストに含まれます。このデータは、ダイアログ・フローで${variable_property_name.value.Param}
を使用できます。
Oracle Visual Builder、Angular、Oracle JavaScript Extension Toolkit (JET)、React.jsなどの様々なフレームワークを使用してSPAを記述できます。
Oracle Visual BuilderのバックエンドによってREST接続、ユーザー(Oracle Identity Cloud Serviceを使用)が管理され、ビジネス・オブジェクトが実行されるため、デジタル・アシスタント内でホストされるOracle Visual Builderアプリケーションには次の制限があります:
- ビジネス・オブジェクトを使用できません。
- Oracle Identity Cloud Serviceとの統合はできません。
- Oracle Visual Builder認証プロキシを使用してRESTサービスにアクセスすることはできません。
デジタル・アシスタント内でアプリケーションをホストするには、これをTARアーカイブ(TGZファイル)にバンドルする必要があります。これはSPAであるため、このパッケージのルートにindex.html
ファイルが存在する必要があります。
SPAが入力パラメータおよびコールバックURLにアクセスできるようにする
window.webViewParameters
変数(次のスニペットに示されている)を実行時にindex.html
ファイルの<head>
要素にインジェクトします。ペイロード内のキー値のペアは、スキルから渡された入力値をSPAに通知します。window.webviewParameters = {
parameters: [
{"key": "variableA", "value": "jsonObjA"},
{"key": "variableB", "value": "jsonObjB"},
...
{"key": "webview.onDone",
"value": "https://host:port/patch"},
]
};
アプリケーションがこれらのオブジェクトにアクセスできるようにするには、window.webviewParameters['parameters']
変数を宣言します:let webviewParameters = window.webviewParameters !=null?window.webviewParameters['parameters']:null;
返されたオブジェクトは、コールバックによってWebビューの「サービスの出力」プロパティに格納されます。
app.js
ファイルの次のスニペットでは、この関数は名前付きキーの値を返します。見つからない場合は、デフォルト値が設定されます。
ヒント:
独自のコードでこのスニペットを使用できます。this.getParam
のかわりにvar 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;
};
index.htmlファイルのプレースホルダの定義
デジタル・アシスタント内でSPAをホストする場合、index.html
ファイル内の変数値にプレースホルダを定義する必要はありません。index.html
ファイルに<head>
要素がある場合、Webアプリケーションは予期される値およびコールバックを認識します。
<head>要素への単一のプレースホルダの追加
<head>
要素内に、webview.sourceVariableList
プレースホルダを含む<script>
ブロックを挿入します。Webアプリケーションは、これを入力パラメータ・データおよびコールバックURLを持つJSONエンコード文字列に置き換えます。
次の例では、キーはwindow.wvParams
です。window.
を付加するかぎり、このキーには任意の名前を使用できます値は常に"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>
次のアプリケーション・コードの例:
let
文は、webview.sourceVariableList
をwvParams
に割り当てます。- 出力値はJSONオブジェクトとして解析されます。
fullname
は、Webビュー・コンポーネントのsourceVariableList
プロパティに定義された変数の名前を抽出します(name
は、定義された変数の名前です)。
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);
...
<head>要素への複数のプレースホルダの追加
SourceVariable
コンポーネントとコールバックURLにそれぞれ定義された値のプレースホルダを含む<script>
ブロックを追加します。Webアプリケーションは、コールバックURLと入力パラメータのデータをJSONエンコード文字列として返します。プレースホルダを追加したため、window.webviewParameters['parameters']
変数を宣言する必要はありません。
SourceVariable
プロパティに定義されている入力値と一致します。webview.
が付加されます(たとえば、webview.keyword
)。
webview.onDone
にする必要があります。次のスニペットで、たとえば、webview.keyword
、webview.assignee
、webview.inventor
はすべてsourceVariableList: "assignee, keyword, inventor"
に一致します。コールバックURLは、webview.onDone
で定義されます。コールバック・キーには任意の名前を付けることができますが、値は常にwebview.onDone
として定義する必要があります。
オプションで、キーにwindow.を付加してグローバル変数を設定できます(たとえば、次のスニペットのwindow.Keyword
)。
<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>
コールバックURLをWebアプリケーションの完了ボタンに関連付ける
Webビュー・コンポーネントによって生成されるコールバックURLは、そのステート・トークン(https://...?state=<callback-state-token>
)のため、基本的にシングルユース・コールバックです。デフォルトのライフタイムは1時間ですが、Webビュー・コンポーネントがWebアプリケーションからのコールバック・リクエストを処理した後、クリアされます。この時点以降、ユーザーはWebアプリケーションに問合せを実行できないため、コールバックURLに関連付けられた「閉じる」ボタンがある最終ページに遷移する必要があります。
外部でホストされるWebビュー
セキュリティ要件がある場合、サーバー側のインフラストラクチャを活用する場合、またはデータ統合あるいは中央管理が必要な場合、外部サーバーでアプリケーションをホストします。リモートでホストされるWebアプリケーションはSPAにできますが、必ずしもそうする必要はありません。既存のWebアプリケーションを変更してWebビューとしてレンダリングするか、またはスキル専用のWebアプリケーションを作成できます。
- 実行時に、Webビュー・コンポーネントは、スキルのコールバックURLとユーザーの入力パラメータをキーと値のペアの配列として含むPOSTリクエストを仲介サービスに送信します。このコンポーネントは、コールバックURLキーとして
webview.onDone
変数を追加します。キーは、Webビューの「サービスの入力」プロパティとwebview.onDone
プロパティの両方によって参照されるパラメータの名前です。{ "parameters": [{ "value": "CDG", "key": "origin" }, { "value": "MUC", "key": "destination" }, { "value": "https://<url>:443/connectors/v2/callback?state=cb5443. ..2c" "key": "webview.onDone" }]
- 仲介サービスは、スキルに単一のプロパティ
webview.url
を持つJSONオブジェクトを返します。その文字列によって、WebアプリケーションへのリダイレクトURLが定義され、それがスキルからの後続のGETリクエストによって使用されます。このURLには、POSTリクエストから渡されたキー値も含まれます(POSTリクエストのペイロードがWebアプリケーションからアクセス可能なストレージに保存されている場合を除く)。これは次のようになります:
Webアプリケーションは、コールのコールバックURLを使用して制御をスキルに戻し、オプションでレスポンス・ペイロードを渡します。{ "webview.url": "https://<app url>?callbackURL=https://example.com:443/connectors/v2/callback?state=cb55435552c&origin=CDG&destination=MUC }
これは、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
メソッドを使用して、origin
、destination
、departureDate
およびreturnDate
キー値ペアを持つJSONオブジェクトをスキルに戻す方法を示しています:{ "origin":"CDC" "destination":"MUC" "departureDate":"15689736000000" "returnDate":"15689736000000" }
ヒント:
このスニペットには、ユーザーがWebアプリケーションでの作業を完了したか取り消したことを示す"success"
または"cancel"
に設定された"status"
プロパティがあります。コールバック・リクエストが完了する前にブラウザを閉じることができるため、まだ発生していない場合はコールバックを発行するクローズ用のリスナーを含めます。コールでは、"cancel"
のステータスを使用して、フォームが正常に完了しなかったことを示すことができます。ユーザーがウィンドウを閉じて、これをキャッチしない場合、スキルはタイムアウトするまで待機します。 - スキルは、
webview.url
プロパティで定義されたURLにGETリクエストを送信することで、Webアプリケーションを起動します。 - Webビューは入力を処理した後、完了コールバック(POSTリクエスト)を、Webビュー・コンポーネントが生成して仲介サービスに提供したコールバックURLに送信します。このリクエストは、アプリケーションが終了した(スキルがセッションの制御を再開する)だけでなく、Webビューの「サービスの出力」プロパティに格納されるデータのペイロードを返すことができます。
ホスティング方針に応じて、次のいくつかのことに注意してください:
- Webアプリケーションと仲介サービスを同じWebサーバー上でホストする場合、スキルのリクエスト・パラメータをセッションに保存できるため、長いURL文字列を使用する必要がありません。
- Webアプリケーションと仲介サービスを異なるサーバー上でホストする場合、スキルに送信されるリダイレクトURLのすべてのWebアプリケーション・リクエスト・パラメータは、問合せパラメータとしてエンコードする必要があります。
Webビュー・サービスの作成
Webビュー・サービスを構成すると、Webビュー・アプリケーションをホストするサービスにスキルが接続されます。
Webビュー・サービスは、「Webビュー」ページから作成します。このページにアクセスするには、左側のナビゲーション・バーで「コンポーネント」()をクリックしてから、「Webビュー」をクリックします。このページには、Webビューの「Webビュー・コンポーネント・サービス」プロパティで参照できる様々なWebビュー・サービスが一覧表示されます。
スキルのバージョンまたはクローニング時に、デジタル・アシスタントによってホストされるサービスを再構成する必要はありません。ただし、Webアプリケーションを外部でホストする場合、スキルのバージョニングまたはクローニング時にサービスを再構成する必要があります。
デジタル・アシスタントでホストされるWebビュー・サービスの作成
外部でホストされるWebビュー・サービスでは、構成の際に認証資格証明の提供が必要になることがありますが、必要なことはWebアプリケーションをTARアーカイブ(TGZファイル)にパッケージ化してからアップロードすることのみです。index.html
ファイルがこのファイルのルート・レベルにある必要があります。
tar -zcvf webapp.tgz *
この例では、-zcvf
コマンドによってwebapp.tgz
というファイルが作成されます。index.htmlファイルのプレースホルダの定義で説明しているように、index.html
ファイルがTGZファイルのルートにあれば、選択したフレームワークを使用してWebアプリケーションを作成できます。実際には、index.html
がルート・レベルの唯一のファイルなることもあります。
- 「名前」ファイルにサービスの名前および説明(オプション)を入力します。ここに入力する名前は、Webビュー・コンポーネントの「Webビュー・コンポーネント・サービス」プロパティの値に一致する必要があります。
- 「ホストされたサービス」オプションをオンに切り替えます。
- TGZを「パッケージ・ファイル」フィールドにドロップするか、参照してTGZファイルを選択します。
- 「作成」をクリックします。
Oracle Visual Builderアプリケーションのパッケージ化
vb-build Gruntタスクを使用して、デジタル・アシスタント用のOracle Visual Builderアプリケーションを作成し、最適化します。このタスクはローカルで実行することも、Oracle Developer Cloud Service (DevCS)でのビルドの一部として実行することもできます。
- Oracle Visual Builderで「直接(プロキシをバイパス)」および「匿名アクセスの許可」を選択して、Webビューをスキルに統合する方法で説明されている制限に対応できるようにサービス接続が構成されていることを確認します。
- Oracle Visual Builderを使用してバイナリを最適化する場合は、「Gitにプッシュ」を選択します。それ以外の場合は、このステップをスキップできます。
Oracle Visual Builderアプリケーションの保護とGitリポジトリへの統合の詳細は、Oracle Visual Builderのドキュメントを参照してください。
Oracle Visual Builderアプリケーションのローカルでのパッケージ化
Oracle Visual Builderアプリケーションをローカルで最適化およびパッケージ化するには:
- Oracle Visual Builderホーム・ページで、アプリケーションを選択し、「データなしでエクスポート」をクリックします。
- アプリケーションを解凍します。
- ルート・フォルダ(
package.json
ファイルとGruntfile.js
ファイルの両方が格納されている)でnpm install
を実行します。npm install
を実行すると、package.json
ファイルに定義されたgrunt-vb-build npm
パッケージが取得されます。 - 次のパラメータを入力します。
./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>
パラメータ 説明 url
Visual BuilderインスタンスのURL。 username
Visual Builderインスタンスのユーザー名。 password
Visual Builderインスタンスのパスワード。 id
アプリケーションのID。アプリケーションIDはアプリケーション名と同じでもかまいませんが、アプリケーションIDはアイデンティティ・ドメイン内で一意である必要があります。 ver
アプリケーションのバージョン。 git
ソースの場所を指定します(ソースが現在のフォルダ内にない場合)。 - ビルドの完了後、アプリケーション・ディレクトリ(
WebApps
ディレクトリにあります)に移動します。たとえば、build/optimized/webApps/financialDispute
です。 - GNU tarコマンド(たとえば、
tar -zcvf webapp.tgz *
)を実行します。tar -zcvf webapp.tgz *
Oracle Developer Cloud Serviceを使用したアプリケーションのパッケージ化
- Oracle CloudでWebアプリケーションのビルド・ジョブを構成します:
- ソース・コントロールとしてGitを追加して、ジョブをGitと関連付けます(WebアプリケーションもGitリポジトリと統合する必要があります)。
- ビルド・テンプレートを選択します。
- ビルドに渡される文字列パラメータを追加します。次のパラメータがあります:
- アプリケーションのサービスURL、IDおよびバージョン(Oracle Visual Builderインスタンスから取得できます)
- ユーザーおよびパスワード(パスワード・パラメータ)
- 最適化(Uglify2など)。
- ビルド・ステップでは、
npm install
で始まり、デフォルトのパラメータをVisual BuilderのGruntタスク(vb-build
など)に渡すシェル・スクリプトを追加します。npm install ./node_modules/.bin/grunt vb-build \ --url=${URL} \ --username=${username} \ --password=${password} \ --id=${id} --ver=${ver} \ --optimize=${optimize} \ --schema=dev \
- ビルド後構成では、「アーティファクト・アーカイバ」(「ビルド後アクションの追加」メニューから選択)を選択し、「アーカイブするファイル」フィールドに
build*zip
と入力して、アーカイブを構成します。
- ビルドの完了後、ZIPファイルをダウンロードして抽出します。
index.html
ファイルは、webapp
フォルダ(webapps
ディレクトリにある)内にあります。 - アプリケーションをTGZファイルにパッケージ化します(たとえば、
tar -zcvf webapp.tgz *
)。
外部でホストされるWebビュー・サービスの作成
- 名前—リモート・サービスの名前。
ノート
ここに入力する名前は、Webビュー・コンポーネントの「Webビュー・コンポーネント・サービス」プロパティの値に一致する必要があります。 - 「ホストされたサービス」トグルをオフに切り替えます。
- WebアプリケーションURL—ソース・パラメータをHTTP POSTリクエストのペイロードとして受け入れる、Webサーバーによって提供されるベース・エンドポイント。たとえば、
https://example.oracle.com:3001/webviewParams
です。Webアプリケーションと仲介サービスが個別にホストされている場合、仲介サービスのURLを入力します。 - 認証トークン—「WebアプリケーションURL」プロパティで指定されたURLへのリクエストとともに送信される認証トークン。このプロパティの形式は、
Basic <token>
またはBearer <token>
です。オプションのプロパティです - 問合せパラメータ—キーと値のペアがPOSTリクエストに追加される問合せパラメータである、文字列化されたJSONオブジェクト。オプションのプロパティです。
ダイアログ・フローでの返されたデータの参照
ペイロードで返される値は変数値を更新しないため、レスポンス・ペイロードのプロパティ名は「サービスの入力」プロパティで定義された変数名と一致する必要はありません。
返されたペイロードには、${variable_property_name.value.Param}
を使用してアクセスできます。


図tester-variables.pngの説明
ヒント:
Webアプリケーション開発者は、返されたペイロードに説明的なプロパティ名が含まれていることを確認する必要があります。