Webビュー

スキルにより、顧客はWebビュー・アプリケーションを使用して構造化データを入力できるようになります。

自然言語での会話は、その性質上、自由に流れるものです。ただし、ユーザーから情報を収集するスキルには、必ずしも最適な方法ではない場合があります。たとえば、クレジット・カードやパスポートの詳細を入力する際には、ユーザーは特定の情報を(正確に)入力する必要があります。このような種類のタスクをサポートするために、スキルでWebビュー・アプリケーションをコールできます。

これらのアプリケーションは、フォーム、日付ピッカー、フィールド、LOVなどのUI要素を介した構造化データの入力を可能にするだけでなく、ユーザー入力を検証し、イメージのアップロード、ユーザー署名の取得、バーコードのスキャンなど、様々な方法で情報を収集することもできます。クレジット・カード番号などの機密ユーザー・データはアプリケーションに入力された際にチャット履歴に表示されないため、Webビュー・アプリケーションはこのデータも保護します。
webview-webapp.pngの説明が続きます
図webview-webapp.pngの説明

Webビューをスキルに統合する方法

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ビュー

デジタル・アシスタント内でホストされるWebアプリケーションは、単一ページ・アプリケーション(SPA)、つまり、Webアプリケーションを起動し、スキル・ユーザーの入力に応じて更新される単一のHTMLページ(index.html)を持つクライアント側Webアプリケーションである必要があります。Webビュー・コンポーネントがSPAをコールすると:
  1. index.htmlがロードされ、WebアプリケーションがWebビューとして、または別のブラウザ・タブで起動されます。
  2. Webビュー・コンポーネントは、ダイアログ・フローで収集されたパラメータ値をコールバックURLとともに渡します。SPAが入力パラメータおよびコールバックURLにアクセスできるようにするでは、これらの値を渡す様々な方法を説明しています。
  3. 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サービスにアクセスすることはできません。
したがって、これらの機能のいずれかをサポートすることは、外部サーバー上でOracle Visual Builderアプリケーションをホストする必要があることを意味します。

デジタル・アシスタント内でアプリケーションをホストするには、これをTARアーカイブ(TGZファイル)にバンドルする必要があります。これはSPAであるため、このパッケージのルートにindex.htmlファイルが存在する必要があります。

SPAが入力パラメータおよびコールバックURLにアクセスできるようにする

デジタル・アシスタント内でSPAをホストする場合、Webビュー・コンポーネントは、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ビューの「サービスの出力」プロパティに格納されます。
Reactアプリケーションの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.sourceVariableListwvParamsに割り当てます。
  • 出力値は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.keywordwebview.assigneewebview.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アプリケーションの場合、Webアプリケーション自体と仲介サービスをホストする必要があります。WebアプリケーションはスキルからのGETリクエストを予期しますが、仲介サービスはスキルのPOSTリクエストを受信して、WebアプリケーションへのリダイレクトURLを形成します。これら2つは同じWebサーバー上に置くことも、個別のWebサーバー上でホストすることもできます。実装に関係なく、リクエスト・フローは次のようになります:
  1. 実行時に、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" 
    }]
    
  2. 仲介サービスは、スキルに単一のプロパティwebview.urlを持つJSONオブジェクトを返します。その文字列によって、WebアプリケーションへのリダイレクトURLが定義され、それがスキルからの後続のGETリクエストによって使用されます。このURLには、POSTリクエストから渡されたキー値も含まれます(POSTリクエストのペイロードがWebアプリケーションからアクセス可能なストレージに保存されている場合を除く)。これは次のようになります:
    {
    "webview.url":
            "https://<app url>?callbackURL=https://example.com:443/connectors/v2/callback?state=cb55435552c&origin=CDG&destination=MUC
    }
    Webアプリケーションは、コールのコールバックURLを使用して制御をスキルに戻し、オプションでレスポンス・ペイロードを渡します。
    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));          
            }
    これは、JQuery $.postメソッドを使用して、origindestinationdepartureDateおよびreturnDateキー値ペアを持つJSONオブジェクトをスキルに戻す方法を示しています:
    {
    "origin":"CDC"
    "destination":"MUC"
    "departureDate":"15689736000000"
    "returnDate":"15689736000000"
    }

    ヒント:

    このスニペットには、ユーザーがWebアプリケーションでの作業を完了したか取り消したことを示す"success"または"cancel"に設定された"status"プロパティがあります。コールバック・リクエストが完了する前にブラウザを閉じることができるため、まだ発生していない場合はコールバックを発行するクローズ用のリスナーを含めます。コールでは、"cancel"のステータスを使用して、フォームが正常に完了しなかったことを示すことができます。ユーザーがウィンドウを閉じて、これをキャッチしない場合、スキルはタイムアウトするまで待機します。
  3. スキルは、webview.urlプロパティで定義されたURLにGETリクエストを送信することで、Webアプリケーションを起動します。
  4. 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ファイルがこのファイルのルート・レベルにある必要があります。

GNU tarコマンドを使用して、アプリケーションをパッケージ化できます:
tar -zcvf   webapp.tgz *
この例では、-zcvfコマンドによってwebapp.tgzというファイルが作成されます。index.htmlファイルのプレースホルダの定義で説明しているように、index.htmlファイルがTGZファイルのルートにあれば、選択したフレームワークを使用してWebアプリケーションを作成できます。実際には、index.htmlがルート・レベルの唯一のファイルなることもあります。
サービスを作成するには:
  1. 「名前」ファイルにサービスの名前および説明(オプション)を入力します。ここに入力する名前は、Webビュー・コンポーネントの「Webビュー・コンポーネント・サービス」プロパティの値に一致する必要があります。
  2. 「ホストされたサービス」オプションをオンに切り替えます。
  3. TGZを「パッケージ・ファイル」フィールドにドロップするか、参照してTGZファイルを選択します。
  4. 「作成」をクリックします。

Oracle Visual Builderアプリケーションのパッケージ化

vb-build Gruntタスクを使用して、デジタル・アシスタント用のOracle Visual Builderアプリケーションを作成し、最適化します。このタスクはローカルで実行することも、Oracle Developer Cloud Service (DevCS)でのビルドの一部として実行することもできます。

Oracle Visual Builderアプリケーションを構築する前に:
  • Oracle Visual Builderで「直接(プロキシをバイパス)」および「匿名アクセスの許可」を選択して、Webビューをスキルに統合する方法で説明されている制限に対応できるようにサービス接続が構成されていることを確認します。
  • Oracle Visual Builderを使用してバイナリを最適化する場合は、「Gitにプッシュ」を選択します。それ以外の場合は、このステップをスキップできます。

    Oracle Visual Builderアプリケーションの保護とGitリポジトリへの統合の詳細は、Oracle Visual Builderのドキュメントを参照してください。

Oracle Visual Builderアプリケーションのローカルでのパッケージ化

Oracle Visual Builderアプリケーションをローカルで最適化およびパッケージ化するには:

  1. Oracle Visual Builderホーム・ページで、アプリケーションを選択し、「データなしでエクスポート」をクリックします。
  2. アプリケーションを解凍します。
  3. ルート・フォルダ(package.jsonファイルとGruntfile.jsファイルの両方が格納されている)でnpm installを実行します。

    npm installを実行すると、package.jsonファイルに定義されたgrunt-vb-build npmパッケージが取得されます。

  4. 次のパラメータを入力します。
    ./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 ソースの場所を指定します(ソースが現在のフォルダ内にない場合)。
  5. ビルドの完了後、アプリケーション・ディレクトリ(WebAppsディレクトリにあります)に移動します。たとえば、 build/optimized/webApps/financialDisputeです。
  6. GNU tarコマンド(たとえば、tar -zcvf webapp.tgz *)を実行します。
    tar -zcvf   webapp.tgz *

Oracle Developer Cloud Serviceを使用したアプリケーションのパッケージ化

Oracle Developer Cloud Service (DevCS)でアプリケーションを作成および最適化するには:
  1. 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と入力して、アーカイブを構成します。
  2. ビルドの完了後、ZIPファイルをダウンロードして抽出します。index.htmlファイルは、webappフォルダ(webappsディレクトリにある)内にあります。
  3. アプリケーションをTGZファイルにパッケージ化します(たとえば、tar -zcvf webapp.tgz *)。

外部でホストされるWebビュー・サービスの作成

外部Webアプリケーション・サーバー上でホストされる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}を使用してアクセスできます。

Webビュー・サービスを作成してWebビュー・コンポーネントを構成したら、スキル・テスター(「テスター」アイコン。)を使用して、Webアプリケーションによって返されたデータについて確認できます。会話がWebビュー状態を過ぎた後、「会話」ウィンドウを使用して、変数に対して返された値を調べます。
tester-variables.pngの説明が続きます
図tester-variables.pngの説明

ヒント:

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