ポータブル仮想エージェント Web クライアントの構成

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

    • ポータブル Web クライアントのチャットウィジェットを構成して、サードパーティの Web ページで仮想エージェントを実行します。

    始める前に

    注:
    Vancouver 以降の新規顧客のオンボーディングの場合、デフォルトでは認証されたユーザーのみが Web クライアントにアクセスできます。認証されていないユーザーが Web クライアントにアクセスできるようにするには、sn_va_web_client_app_embed ページでパブリックアクセスを有効にする必要があります。詳細については、「Make UI pages public or private」を参照してください。

    必要なロール：admin

    このタスクについて

    ServiceNow トップレベルドメインとドメイン名が Web クライアントをロードしているサイトと一致する場合にのみ、ポータブル仮想エージェントがサポートされます。SSO は、service-now.com URL を介してのみサポートされます。それを超える場合、カスタムソリューションと実装が必要です。

    手順

    1. [すべて] に移動してから、フィルターに「sys_properties.list」と入力します。
    2. システムプロパティ [sys_properties] テーブルで、com.glide.cs.embed.csp_frame_ancestors プロパティを名前で検索します。
    3. プロパティ名をクリックしてフォームを開き、ディレクティブ値を指定します。
      フィールド 説明
      タイプ 文字列

      これがデフォルト値です。
      値 HTTP ヘッダーディレクティブのソース値：Content-Security-Policy:frame-ancestors<source> このプロパティは、Internet Explorer を除くほとんどの主要なブラウザーに適用されます。
      以下を含む 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 プロパティを名前で検索します。
    5. プロパティ名をクリックしてフォームを開き、ディレクティブ値を指定します。
      フィールド 説明
      タイプ 文字列

      これがデフォルト値です。
      値 ブラウザーがフレーム内に外部 Web ページをレンダリングできるかどうかを示す、X-Frame-Options ヘッダーディレクティブの値。
      次のいずれかの値を指定します。
      • sameorigin：ページ自体と同じ作成元を持つフレームにページを表示します。これがデフォルト値です。このプロパティは、Internet Explorer 11 などの古いブラウザーに適用されます。例の値：allow from https://example.com
      • deny：フレームにページを表示しません。
      • allow-from uri：指定した作成元のフレームにのみ、ページを表示します。
        注:
        この値は、最近のブラウザーでは機能しなくなっています。

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

    6. ドメイン間でアクセスできるように REST API の CORS ルールを設定します。
      このルールにより、Web ページ上のチャットウィジェットへのアクセスを提供する API を、セキュリティ上の制約なしで呼び出す権限が、指定した Web ドメインに付与されます。すべてのドメインは、共通の親ドメインを共有する必要があります。また、サポートするサブドメインごとに新しい CORS ルールを作成する必要があります。
      1. 移動先 すべて > System Web Services > REST > CORS ルール.
      2. [新規] をクリックします。
      3. フォームのフィールドに入力します。
        フィールド 説明
        名前 ルールの一意の名前。
        アプリケーション アプリケーションのスコープデフォルト値は「グローバル」です。
        REST API REST API の名前。[会話コンシューマーアカウント [now/cs]] を選択します。
        ドメイン Web サイトのドメイン。例：https://mycompany.com

        Web サイトに複数のサブドメインがある場合は、それぞれに対して CORS ルールを作成する必要があります。たとえば、support.mycompany.com と products.mycompany.com には 2 つの別々の CORS ルールが必要です。

        注:
        ワイルドカードは使用できません。
        最大経過時間 クライアントセッションをキャッシュする秒数。最初の CORS 要求の後、指定された時間内に出された同じクライアントからの追加の要求には、プリフライトメッセージは必要ありません。

        値を指定しない場合、デフォルト値の 0 は、すべての要求にプリフライトメッセージが必要であることを示します。
      4. [HTTP メソッド] タブで、[GET] を選択します。
        ポータブル Web クライアントは要求のみを受信します。
      5. [送信] をクリックします。
      6. オプション: ポータブル Web クライアントを Web サイトの別のサブドメインに追加する場合は、これらのステップを繰り返します。
    7. オプション: 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(<your-page>);
      
      // 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/"https://<your-instance>service-now.com/sn_va_web_client_login.do?sysparm_redirect_uri=’ + encodeURIComponent(<your-page>);
    });
  </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 クライアントページにユーザーがリダイレクトされます。

    次のタスク

    サードパーティ Web サイトにポータブル仮想エージェント Web クライアントを追加する。