Oracle Cloud Infrastructureドキュメント

Oracle Web

Digital Assistant Client SDK for Oracle webでは、Webページでスキルを実行できます。 また、チャットを実行するウィジェットのルック・アンド・フィールをカスタマイズできます。

SDKは、Oracle Digital Assistantとスキルの間にあるOracle ChatおよびAttachment Handlerサーバーにアタッチします。 次にチャット・サーバーは、メッセージを処理するスキルに渡し、スキル・レスポンスをクライアントに送信します。
ノート

クライアントがサーバーから切断されても、Oracle Webチャネルはメッセージを格納しません。
接続しているクライアントにのみメッセージを配信します。

Oracle Webチャネルの構成

2つのモードでOracle Chat Serverに接続するようにチャネルを構成できます: 認証済または認証されていません。
  • 認証モード - 認証は、JSON Webトークン(JWT)を使用して強制されます。 バックエンド・サーバーは、ユーザーがwebアプリで認証する際に、Oracle Webチャネルから生成された秘密キーを使用してこれらのトークンを生成します。 その後、サーバーはトークンをクライアント(通常はブラウザ)に送信します。 これらのトークンは、すべてのHTTPリクエストで送信されるため、サーバーがユーザーを認証できます。 トークンに含まれる情報は、サーバーが所有する秘密キーで署名されます。 サーバーは、クライアントからトークンを取得すると、クライアントから送信されたシグネチャと、秘密キーを使用して生成したシグネチャを比較します。 トークンは、2つのシグネチャが同じ場合に有効です。

    クライアントがチャット・サーバーとのwebソケット接続を確立する必要がある場合、最初にバックエンド・サーバーからJWTトークンをリクエストし、次にトークンをチャット・サーバーへのコールで認可ヘッダーに追加します。

  • 未認証モード - 認証されたユーザーがすでに保護されていて表示可能な場合、静的webサイトのため、または認証メカニズムがない場合、クライアントが署名付きJWTトークンを生成できない場合、認証されていないモードを使用します。
Oracle Webチャネルを構成するには:
  1. メニューから開発チャネルの順に選択します。
  2. ユーザーを選択します。
  3. チャネルの追加をクリックし、チャネル・タイプとしてOracle Webをクリックします。
  4. ダイアログを完了します:
    • チャネル名を入力してください
    • 認証済接続の場合:
      • クライアント認証の有効化のトグルを切り替えて、SDKがクライアント認証可能チャネルに接続しているかどうかを確認します。
      • 最大.トークンの有効期限(分)フィールドに、JWTトークンの最大時間を設定します。
    • 認証されていない接続の場合:
      • クライアント認証の有効化トグルをオフにします。
      • チャット・サーバーへの接続に許可されるドメインのリストを入力します。
    • セッションの有効期間を設定します。
    • 「作成」(コールバック)をクリックします。 Oracle Digital Assistantによって、SDKを初期化するために必要なチャネルIDと秘密キーが生成されます。 チャット・ウィジェットをホストするようにHTMLページを構成する際に必要になるため、簡単に閉じます。
  5. チャネル有効をOnに切り替えます。
  6. スキルまたはDigital Assistantにチャネルをルーティングします。

SDKのインストール

HTMLページの<script>タグを、提供するコードに更新して、SDKをインストールします:
  1. Oracle Technology Networkの「ODAおよびOMCのダウンロード・ページ」からOracle Web SDK v1.0をダウンロードします。
  2. web-sdk.jsをプロジェクト・ディレクトリに保存します。 ファイルのロケーションに注意してください。これは、<script>タグ・コードで<WebSDK URL>プロパティを定義するために必要になります。
  3. 次の<script>タグをHTMLページの<head>要素の最後に追加します:
    
    <script>
        var chatWidgetWebSettings = {
            URI: '<Server URI>',
            channelId: '<Channel ID>',
            userId: '<User ID>'
        };
        function initSdk(name) {
            // Default name is Bots
            if (!name) {
                name = 'Bots';
            }
            setTimeout(() => {
                window[name] = new WebSDK(chatWidgetSettings);  // Initiate library with configuration
                window[name].connect()                          // Connect to server
                    .then(() => {
                        console.log("Connection Successful");
                    })
                    .catch((reason) => {
                        console.log("Connection failed");
                        console.log(reason);
                    });
            });
        }
    </script>
    <script src="<WebSDK URL>" onload="initSdk('<WebSDK namespace>')">
  4. 次のプロパティを定義します。
    • URI - Oracleチャットおよびアタッチメント・ハンドラ・サーバーのURI。 これは必須プロパティーです。
    • channelId - Oracle Webチャネルの作成時に生成されるチャネルID。 ウィジェットを基礎となるスキルに接続するため、このプロパティは必須です。
    • userId - ユーザーID。 この値は指定できますが、まだ指定していない場合はSDKによってこの値が生成されます。 このプロパティは、認証されていない接続ではオプションです。
    • <WebSDK URL> - web-sdk.jsファイルのロケーション。 例えば: "./scripts/web-sdk.js" これは必須プロパティーです。
    • <WebSDK namespace> - このネームスペースを使用して、パブリックAPIを呼び出します。 たとえば、ネームスペースをBotsに設定する場合、APIをBots.<API>()として起動します。
      (window, document, "./scripts/web-sdk.js", "Bots");
      APIの詳細は、SDKリファレンスを参照してください。

クライアント認証の構成

認証モードの場合、URIchannelIdおよびuserIdプロパティを定義する必要があります。 さらに、次のように<script>タグ・コードを構成します:
  • clientAuthEnabledプロパティをtrueとして渡します。
  • 認可ヘッダー(Authorization: Bearer <JWT>)で設定されたJWTトークンの生成および受渡しに使用できる関数を含めます。
    ヘッダーには次のトークン要求が必要です: channelIdURIuserIdおよび要求名iat (一度に発行)およびexp (有効期限)です。iatは、トークンが発行された時間を示します。 これは、UNIXエポック以降に経過した秒数を表す数値である必要があります。expは、UNIXエポック以降に経過した秒数を表す数値である必要があります。 発行された時間(iat)の30分以上後に、有効期限を設定することをお薦めします。 デコードされたヘッダーは次のようになります:
    {
    
     "alg": "HS256",
    
     "typ": "JWT"
    
    }
    デコードした本文の例を次に示します:
    {
    
      "iat": 1569828182,
    
      "exp": 1569831782,
    
      "channelId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    
      "userId": "John"
    
    }
    ノート

    この例で示されているトークンは署名されていません。
    実際のトークンは、チャネル・シークレット・キーで署名されます。
認証モードのコードは次のとおりです:
<script>
    var chatWidgetWebSettings = {
        URI: '<Server URI>',
        clientAuthEnabled: true
    };
    var generateToken = function() {
        return new Promise((resolve) => {
            fetch('https://yourbackend.com/endpointToGenerateJWTToken').then((token) => {
                resolve(token);
            })
        });
    }
    function initSdk(name) {
        // Default name is Bots
        if (!name) {
            name = 'Bots';
        }
        setTimeout(() => {
            window[name] = new WebSDK(chatWidgetSettings, generateToken);   // Initiate library with configuration
            window[name].connect()                                          // Connect to server
                .then(() => {
                    console.log("Connection Successful");
                })
                .catch((reason) => {
                    console.log("Connection failed");
                    console.log(reason);
                });
        });
    }
</script>
<script src="<WebSDK URL>" onload="initSdk('<WebSDK namespace>')">

チャット・ウィジェットのカスタマイズ

チャット・ウィジェットは、レイアウトとアイコン、色、テキストなど、様々な面でカスタマイズできます。

ネットワークの構成

次のプロパティを使用して、SDKをインストールします。
プロパティ名 必須? デフォルト値 説明
URI はい 該当なし Oracleチャットおよびアタッチメント・ハンドラ・サーバーのURL
channelId はい 該当なし Oracle WebチャネルのチャネルID
userId いいえ ランダムに生成された値 ユーザーの一意の識別子。 これを指定しない場合、Oracle Digital Asssistantが1つ生成します。
clientAuthEnabled はい false SDKが、クライアント認証が有効なチャネルに接続しているかどうかを確認します。 「クライアント認証の構成」で説明しているように、認証を有効化してチャネルに接続し、JWTトークンを使用するには、これをtrueに設定します。

機能フラグ

次に機能フラグ・プロパティを使用します:
  • セキュア接続
  • ピボット形のアクション・ボタン
  • スキル・レスポンスのオーディオ・ナレーション。
  • アタッチメントの共有
  • 前回の(フォーカス外)メッセージのクリックの無効化
例えば:
     <script>
        var chatWidgetSettings = {
            URI: YOUR_URI,
            channelId: YOUR_CHANNELID,
            enableClearMessage: true,
            enableLocalConversationHistory: true,
            enableTimestamp: true,
            showConnectionStatus: true,
            showTypingIndicator: true,
            disablePastActions: 'all',
...
         };

...
    </script>
プロパティ名 必須? デフォルト値 説明
displayActionsAsPills いいえ false ピボット操作ボタンを表示します。
enableAttachment いいえ true アタッチメント共有を構成します。
enableBotAudioResponse いいえ false スキル・レスポンスを構成します。 スキル・レスポンスはWeb APIを使用して読み取られます。
enableClearMessage いいえ false チャット・ウィジェット・ヘッダーのメッセージのクリア・ボタンを有効にします。
enableLocalConversationHistory いいえ false ウィジェットの初期化が完了すると、指定されたuserIdに関連付けられている、ブラウザにロードされる前の会話を有効にします。
enableSecureConnection いいえ true セキュアな通信(https v. httpおよびwss v. ws)を構成します。
enableTimestamp いいえ true メッセージの"読取り"タイムスタンプを有効にします。
openChatOnLoad いいえ false ページのロード時にチャット・ウィジェットを展開します。
showConnectionStatus いいえ false チャット・ウィジェット・ヘッダーに接続ステータスを表示できるようにします。
showTypingIndicator いいえ true レスポンスを待っているときにチャット・バブルを表示します。
disablePastActions はい all ユーザーがすでに操作しているメッセージでボタンのクリックを無効にします。 指定できる値は、allnoneまたはpostbackです。

機能

機能プロパティを使用して次のことを実行します:
  • スキルによって開始される会話を指します。
  • スクロールまたは固定(スティッキー)なチャット・ウィンドウの上部および下部にコンテンツを埋め込みます。
  • ロケールを設定します。
  • デバッグ・モードを設定します。
プロパティ名 必須? デフォルト値 説明
customHeaderElementId いいえ 該当なし チャット・ウィジェットのヘッダーに追加される<div>要素のid。 チャット・ウィジェット・ヘッダーの追加要素に使用されます。
delegate いいえ 該当なし 特定のイベントが会話内で発生する前にコールバックを受信するように委任を設定するオブジェクト。
targetElement いいえ widgetDiv チャット・ウィジェットが埋め込まれるdiv要素。
embeddedVideo いいえ false テキスト・メッセージにYouTubeビデオ・リンクを埋め込むことができます。
embedTopStickyId いいえ 該当なし チャットの上部に表示されるスティッキー・コンテンツに使用される要素のID。 このプロパティを使用して、チャット・ウィジェット会話ビューにカスタム・コンテンツを追加します。 「非スコアリング・コンテンツ: 例」も参照してください。
embedBottomScrollId いいえ 該当なし チャット下部のスクロール・コンテンツとして追加される要素のID。 このプロパティを使用して、チャット・ウィジェット会話ビューにカスタム・コンテンツを追加します。
embedBottomStickyId いいえ 該当なし チャット下部に表示されるスティッキー・コンテンツに使用される要素のID。 このプロパティを使用して、チャット・ウィジェット会話ビューにカスタム・コンテンツを追加します。
isDebugMode いいえ false デバッグ・モードを有効化します。
initUserHiddenMessage いいえ 該当なし 会話を開始するために使用されるユーザー・テキスト・メッセージ。 チャット・ウィジェットの準備が完了すると送信されるこのメッセージは、実際はチャットに表示されません。 例えば: initUserHiddenMessage: 'Hi'
i18n いいえ {'en-us':{…}} localeフィールドを含むオブジェクト。 各ロケールでは、ウィジェットで使用されるテキスト文字列に対するi18nキーと値のペアが保持されます。
locale いいえ en-us テキストのスキルのデフォルト・ロケール。 使用可能な場合、ブラウザのil8n翻訳がスキルのかわりに使用されます。 そうでない場合は、スキル事業所の翻訳が使用されます。
messageCacheSizeLimit いいえ 2000 localStorageに一度に保存できるメッセージの最大数。
readMark いいえ ¿ 既読メッセージの記号で、enableTimestampfalseに設定されている場合は使用不可です。

レイアウト

レイアウト・プロパティを使用して、次のことを行います:
  • webページ内でのウィジェットの位置を設定します。
  • チャット・ウィジェットのディメンション、色およびフォント・スタイルを設定します。
  • ウィジェット内のメッセージのパディングを設定します。
  • ボット・ボタンに関して、通知バッジ・アイコンの位置を設定します。
  • ウィジェット内の会話の開始位置を設定します。
例えば:
     <script>
        var chatWidgetSettings = {
            URI: YOUR_URI,
            channelId: YOUR_CHANNELID,
            font: '14px "Helvetica Neue", Helvetica, Arial, sans-serif', //layout modification property
            height: '60vh', //layout modification property
            width: '20vw',  //layout modification property
             "colors": {    //custom colors property  
                "branding": "#01538A",
                "text": "#B20637"
            },
         }
                
...
    </script>
プロパティ 必須 デフォルト値 説明
badgePosition いいえ {"top": "0", "right": "0"} アイコン・ボタンに関するバッジ・アイコンの位置。
いいえ {"branding": "#1B8FD2", "text": "#212121", "textLight": "#737373"} チャット・ウィジェットで使用される色。
conversationBeginPosition いいえ top ウィジェットにおける会話の開始位置。 topに設定すると、最初のメッセージがウィジェットの上部に表示されます。 bottomに設定されている場合、会話は下部から開始されます。
font いいえ 16px "Helvetica Neue", Helvetica, Arial, sans-serif チャット・ウィジェットで使用されるフォント。
height いいえ 70vh 「<length>データ型」値の1つによって設定されるチャット幅の高さ。
messagePadding いいえ 15px チャット・ウィジェットのメッセージを囲むパディング。
position いいえ {bottom: '20px', right: '20px'} ブラウザ・ウィンドウでのチャット・ウィジェットの配置。 これはJSONオブジェクトとして渡される必要があります。
width いいえ 30vw 「<length>データ型」値の1つに設定されているチャット・ウィジェットの幅。

カスタム・アイコン

スキル・アイコンやチャット・ロゴ・アイコン、スキルおよびユーザーのアバター・アイコンなど、様々なアイコンを作成できます。 例えば:
   <script>
    var chatWidgetWebSettings = {
        URI: YOUR_URI,
        channelId: YOUR_CHANNELID,
        font: '14px "Helvetica Neue", Helvetica, Arial, sans-serif',
        height: '60vh',
        width: '20vw',
         "colors":{
            "branding": "#01538A",
            "text": "#B20637",
    },
    botButtonIcon: 'images/Robot.png',
    logoIcon: 'images/logo.png',
    botIcon: 'images/Robot.png',
    personIcon: 'images/userIcon.png',
    locale: 'en-us', 
    i18n: {
      
        "en-us":{
        "chatTitle": "Support"
        }
    }
    };
...
</script>
プロパティ 必須? デフォルト値 説明
botButtonIcon いいえ 該当なし スキル・ボタンのイメージURL
logoIcon いいえ 該当なし ウィジェットのヘッダーに表示される、スキル・ロゴのイメージURL。
botIcon いいえ 該当なし スキル・レスポンスの横に表示されるスキル(アバター)を表すイメージのイメージURL。 このアイコンは、このプロパティを定義する場合のみ表示されます。
personIcon いいえ 該当なし ユーザーを表すイメージのURL (ユーザーの回答の横に表示)。 このイメージは、このアイコンを定義するときにのみ表示されます。
chatBubbleIcon いいえ 該当なし チャット・バブル・アイコンのイメージのURL。
chatBubbleIconHeight いいえ 42px ロード・チャット・バブル・アイコンの高さ。
chatBubbleIconWidth いいえ 56px ロード・チャット・バブル・アイコンの幅。
audioIcon いいえ 該当なし アタッチのイメージ・タイプのイメージ・アイコンのURL。アタッチ・ソースのURLに到達できない場合に表示されます。
fileIcon いいえ 該当なし ファイル・タイプ・アタッチメントのイメージURL。
imageIcon いいえ 該当なし ソースURLに到達できない場合に表示されるビデオ・タイプ・アタッチメントのイメージURL。
videoIcon いいえ 該当なし ビデオ・アタッチメント・タイプのURLです。これは、ソースURLに到達できない場合に表示されます。
sendIcon いいえ 該当なし 送信アイコンに使用されるイメージのURL。
errorIcon いいえ 該当なし エラー・アイコンに使用されるイメージのURL。

カスタム・カラー

ウィジェットの色はカスタマイズできます。 次のスニペットに示すように、16進色を使用してキーを定義します。
"colors": {
    "branding": "#e00",
    "text": "#545454"
}
キー デフォルト値 説明
branding #1B8FD2 ウィジェット・ブランディングのプライマリ色。 ヘッダーのバックグラウンドとして使用される色およびフッター・ボタンのホバー色として使用される色。
text #212121 チャット・ウィジェットでのメッセージのテキストの色。
textLight #737373 メッセージのセカンダリ・テキストのテキストの色(チャット・ウィジェットのカードの説明など)。

カスタム・テキスト

次の文字列をカスタマイズして、ローカライズされたテキストとして指定できます。 次のオブジェクトで示すように、ローカリゼーションでは、各エントリに対して有効なロケールを提供する必要があります。 en-us以外のロケールのすべてのキーを更新する必要があります。 表示されていない場合は、欠落している値に対してen-us翻訳が表示されます。
"i18n": {
    "fr": {
        "chatTitle": "Soutien"
    },
    "en-us": {
        "chatTitle": "Support"
    },
    "es": {
        "chatTitle": "Apoyo"
    },
    "zh-cn": {
        "chatTitle": "¿¿"
    }
}
キー デフォルト値 説明
audioResponseOff Audio response off ユーザーがヘッダーのオーディオ発話オン・ボタンにマウスを置いたときに表示されるツールチップ。
audioResponseOn Audio response on ヘッダーのオーディオ発話オフ・ボタンにユーザーがマウスを置いたときに表示されるツールチップ。
cardImagePlaceholder イメージをロード中 カード・イメージがフェッチされてロードされるときに表示されるプレースホルダー・テキスト。
chatTitle アスク ヘッダーに表示されるチャット・ウィジェットのタイトル。
clear Clear ユーザーがヘッダーのメッセージのクリア・ボタンにマウスを移動すると表示されるツールチップ。
close Close ユーザーがヘッダーのウィジェットを閉じるボタンにマウスを置いたときに表示されるツールチップ。
クローズ Closing チャット・ウィジェットとサーバー間の接続を閉じているときに表示されるステータス・テキスト。
connected Connected チャット・ウィジェットとサーバー間の接続が確立されたときに表示するステータス・テキスト。
connecting Connecting チャット・ウィジェットがチャット・サーバーに接続したときに表示されるステータス・テキスト。
disconnected 切断 チャット・ウィジェットとサーバー間の接続が閉じられたときに表示するステータス・テキスト。
inputPlaceholder メッセージの入力 ユーザー入力フィール