仮想エージェント Web クライアントを外部 Web ページに埋め込む (従来の方法)

  • リリースバージョン: Xanadu
  • 更新日 2024年08月01日
  • 所要時間：11分

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

    始める前に

    重要:
    代わりに、ポータブル 仮想エージェント Web クライアントを Web ページに追加することを検討してください。コードの複雑さが軽減され、実装が簡単になります。また、チャットを開始または終了するためのクリックアクションなど、標準的なチャット機能も含まれています。詳細については、「サードパーティ Web サイトにポータブル仮想エージェント Web クライアントを追加する」を参照してください。
    • iframe で、埋め込むインスタンスの URL を指定します。ServiceNow インスタンスにないページに Web クライアントを埋め込む場合は、URL をカスタムインスタンス URL にする必要があります。ブラウザのセキュリティ強化のため、カスタム URL を使用しないと Web クライアントのロードに失敗する場合があります。カスタム URL の使用法の詳細については、「インスタンスへのカスタム URL の関連付け」を参照してください。
      カスタム URL を使用するには、次の手順を実行します。
      注:
      デフォルトでは、仮想エージェント Web クライアントは Safari の iframe からは機能しません。Apple はクロスオリジン iframe をブロックします (iframe で使用される URL のドメインが Web サイト自体のドメインと一致しない場合)。

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

      SSO 認証をトリガーするには、認証を実行するための条件を定義し、指定した Web クライアントページにユーザーをリダイレクトする 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 クライアントのセキュリティポリシー、つまり、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」および「仮想エージェント埋め込みクライアントコンテンツのセキュリティポリシー (インスタンスセキュリティ強化)」を参照してください。

      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。指定した作成元のフレームにのみ、ページを表示します。
          注:
          この値は、最近のブラウザーでは機能しなくなっています。

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

    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 認証をトリガーするイベント条件を定義し、指定する Web クライアントページにユーザーを返す JavaScript スクリプトを作成します。
      ユーザーを Web クライアントページにリダイレクトするには、次の文字列を使用します。"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 web client 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 web client
      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>) で指定した埋め込み Web クライアントページにユーザーがリダイレクトされます。