外部 Web ページへの 仮想エージェント チャットウィジェットの埋め込み (従来の方法)

インラインフレーム要素 (iframe) を使用して、 仮想エージェント チャットウィジェットインターフェイスを外部 Web ページにロードします。オプションで、シングルサインオン (SSO) 認証プロセスが、チャットウィジェットを使用しているがログインしていないゲストユーザーに対して自動的に実行されるようにすることもできます。

始める前に

重要:

代わりに、ポータブル 仮想エージェント Web クライアントを Web ページに追加することを検討してください。コードの複雑さが軽減され、実装が簡単になります。また、チャットを開始または終了するためのクリックアクションなど、標準的なチャット機能も含まれています。詳細については、「サードパーティ Web サイトへのポータブル 仮想エージェント チャットウィジェットの追加」を参照してください。

• iframe で、埋め込むインスタンスの URL を指定します。ServiceNowインスタンス上にないページにチャットウィジェットを埋め込む場合、URL はカスタムインスタンス URL である必要があります。ブラウザのセキュリティ強化のため、カスタム URL を使用しないとチャットウィジェットのロードに失敗する場合があります。カスタム URL の使用法の詳細については、「インスタンスへのカスタム URL の関連付け」を参照してください。
  カスタム URL を使用するには、次の手順を実行します。

  • インスタンスでカスタム URL プラグイン (com.snc.customurl) をアクティブ化します。
  • カスタム URL (以前に購入して登録したもの) をインスタンスに追加します。
  注:

  デフォルトでは、 仮想エージェント チャットウィジェットは Safari の iframe からは機能しません。 Apple はクロスオリジン iframe をブロックします (iframe で使用される URL のドメインが Web サイト自体のドメインと一致しない場合)。

• 仮想エージェントクライアントを埋め込んだ後、オプションでチャットウィジェットから SSO 認証をトリガーできますが、これはインスタンスが外部 SSO プロバイダーを使用するように設定されている場合に限られます。ホスティングサイトでも、インスタンスと同じ SSO プロバイダーを使用する必要があります。SSO プロバイダーの設定の詳細については、「外部シングルサインオン (SSO)」を参照してください。

  SSO 認証をトリガーするには、認証を実行するための条件を定義し、指定したチャットウィジェットページにユーザーをリダイレクトする JavaScript スクリプトを作成します (以下のステップ 2 を参照)。com.glide.cs.web_client_login_redirect_urls システムプロパティでそれらを識別することによって、このスクリプトで渡すことができる許可された URL を指定することもできます。完全なリダイレクト URL または URL のホスト部分 (https://example.com など) を指定します。

必要なロール：admin

このタスクについて

この手順では、次の 2 つのシステムプロパティの値を設定する必要があります。

• com.glide.cs.embed.csp_frame_ancestors
• com.glide.cs.embed.xframe_options

これらのプロパティは、埋め込みチャットウィジェットのセキュリティポリシー、つまり、Web チャットクライアントを埋め込む前に、iframe 内で 仮想エージェント チャットおよび ライブエージェント チャットの HTML コンテンツをブラウザーがレンダリングして保護する方法を決定します。

ゲストユーザーの SSO 認証を生成するには、window.postMessage() メソッド (Web API) を使用して認証をトリガーし、認証後にユーザーがリダイレクトされる URL を指定するスクリプトを作成します。このメソッドとウィンドウオブジェクトの詳細については、「Window.postMessage()」を参照してください。

注:

コンテンツ管理システム (CMS) アプリケーションを使用して Now Platform および ServiceNow® アプリケーションのカスタムインターフェイスを作成している場合は、仮想エージェントをサポートしていないことに注意してください。

手順

1. iframe コンテンツを保護するための HTTP ヘッダーディレクティブを指定する com.glide.cs.embed.csp_frame_ancestors および com.glide.cs.embed.xframe_options システムプロパティを設定します。
   HTTP ヘッダーディレクティブは、クリックジャッキングの試行を軽減するために特定のドメインにページを埋め込むことができるかどうかをブラウザーに指示します。両方のプロパティを設定すると、主要なブラウザーと Internet Explorer などの古いブラウザーのセキュリティディレクティブが確実に存在するようになります。
   1. ナビゲーションフィルターで、「sys_properties.list」と入力します。
   2. システムプロパティ [sys_properties] テーブルで、com.glide.cs.embed.csp_frame_ancestors プロパティを名前で検索します。
      注:

      このプロパティは、HTTP ヘッダーディレクティブのソース値を設定します：Content-Security-Policy:frame-ancestors<source>。host-source 値を使用して、外部 Web ページを埋め込むことができるドメインを指定します。このプロパティは、Internet Explorer を除くほとんどの主要なブラウザーに適用されます。
   3. プロパティ名をクリックしてフォームを開き、ディレクティブ値を指定します。

      表 : 1. システムプロパティ：com.glide.cs.embed.csp_frame_ancestors

      フィールド	説明
      タイプ	文字列 これがデフォルト値です。
      値	以下を含む 1 つ以上のソースを指定します。 'self'：作成元が、提供されているページと同じであることを示します。たとえば、値が 'self' http://mywebsite.com の場合、iframe は親ドメインと mywebsite.com に埋め込まれます。これがデフォルト値です。 host-source：外部 Web ページを埋め込むことができるドメイン。名前、IP アドレス、またはオプションの URL やポート番号によるインターネットホストサイトを指定します。サイトアドレスの先頭にワイルドカード (アスタリスク) 文字を使用できます。値の例：http://*.example.com scheme-source：スキーマ。例：http: または https: none：一致する URL がありません。

      指定できるソース値の詳細については、「CSP:frame-ancestors」および「Hardening settings の「仮想エージェント埋め込みクライアントコンテンツのセキュリティポリシー (インスタンスセキュリティ強化)」を参照してください。

   4. システムプロパティ [sys_properties] テーブルに戻り、com.glide.cs.embed.xframe_options プロパティを名前で検索します。
      注:

      このプロパティは、X-Frame-Options ヘッダーディレクティブの値を設定し、ブラウザーがフレーム内に外部 Web ページをレンダリングできるかどうかを示します。デフォルトの sameorigin 値を使用して、外部 Web ページを埋め込むことができるドメインを指定します。このプロパティは、Internet Explorer 11 などの古いブラウザーに適用されます。
   5. プロパティ名をクリックしてフォームを開き、ディレクティブ値を指定します。

      表 : 2. システムプロパティ：com.glide.cs.embed.xframe_options

      フィールド	説明
      タイプ	string。デフォルト値。
      値	次のような値を指定します。 sameorigin。デフォルト値。ページ自体と同じ作成元を持つフレームにページを表示します。値の例：allow from https://example.com。 deny。フレームにページを表示しません。 allow-from uri。指定した作成元のフレームにのみ、ページを表示します。 注: この値は、最近のブラウザーでは機能しなくなっています。

      指定できるソース値の詳細については、「Hardening settings の X-Frame-Options とSet Xframe options to prevent embedding third-party websites [Updated in Security Center 1.3]」を参照してください。

2. ServiceNow インスタンスをカスタム URL に関連付けた後、iframe 要素を作成し、仮想エージェントクライアントを外部 Web ページに埋め込むために使用するインライン要素 (iframe) にカスタム URL を指定します："https://<your-domain>.com/sn_va_web_client_app_embed.do"
   注:

   インスタンスには複数のカスタム URL を設定できますが、インスタンス URL は 1 つのみです。カスタムインスタンスの URL のみを使用する必要があります。

   例：

   <iframe id="sn_va_web_client"     title="ServiceNow Virtual Agent Client"     width="600"     height="900"     src="https://<your-domain>.com/sn_va_web_client_app_embed.do">
   "https://<your-domain>.com/"https://<your-domain>.com/</iframe>
   

   注:

   URL の最後に ?sysparm_skip_load_history=true パラメーターを使用して、会話履歴なしでインターフェイスを読み込みます。
3. オプション: window.postMessage() メソッド (Web API) を使用して、ユーザーインターフェイスページで SSO 認証をトリガーし、指定したチャットウィジェットページにユーザーを戻すイベント条件を定義する JavaScript スクリプトを作成します。
   ユーザーをチャットウィジェットページにリダイレクトするには、次の文字列を使用します: "https://<your-instance>.service-now.com/sn_va_web_client_login.do?sysparm_redirect_uri=' + encodeURIComponent(<your-page>)

   注:

   スクリプトを実行する前に、 com.glide.cs.web_client_login_redirect_urls システムプロパティを使用して、スクリプトで渡すことができる URL を指定します。リダイレクトは、プロパティ値に許可された URL を 1 つ以上指定した場合にのみ機能します。完全なリダイレクト URL または URL のホスト部分 (https://example.com など) を指定します。

   スクリプト例：

   <script>
       window.addEventListener("message", function(e) {
          // redirect to SSO login if the chat widget logs in but is logged in as a guest user(unauthenticated)
         if(e.data.type==="SESSION_CREATED" && e.data.authenticated === false)
           window.location.href = "https://<your-instance>.service-now.com/sn_va_web_client_login.do?sysparm_redirect_uri="+ encodeURIComponent(location.href);
         
         // redirect to SSO login if the ServiceNow platform logs out from underneath the chat widget
         if(e.data.type==="SESSION_LOGGED_OUT")
           window.location.href = "https://<your-instance>service-now.com/sn_va_web_client_login.do?sysparm_redirect_uri=" + encodeURIComponent(location.href);
       });
     </script>

   この例では、SESSION_CREATED または SESSION_LOGGED_OUT イベントが発生したときに、指定されたインスタンスで認証がトリガーされます。認証後 (ユーザーの SSO 認証情報が承認された後)、com.glide.cs.web_client_login_redirect_urls プロパティでページ URL も指定している限り、ユーザーは sn_va-web_client_login.do?sysparm_redirect_uri=' + encodeURIComponent(<your-page>) で指定した埋め込みチャットウィジェットページにリダイレクトされます。