Chat-Widget Virtual Agent in externe Webseite einbetten (veraltet)

  • Freigeben Version: Yokohama
  • Aktualisiert 30. Januar 2025
  • 5 Minuten Lesedauer

    • Laden Sie die Chat-Widget-Schnittstelle Virtual Agent mithilfe eines Inline-Frame-Elements (iframe) auf eine externe Webseite. Optional können Sie auch die automatische Ausführung des SSO-Authentifizierungsprozesses (Single Sign-on) für Gastbenutzer aktivieren, die das Chat-Widget verwenden und nicht angemeldet sind.

    Vorbereitungen

    Wichtig:
    Erwägen Sie stattdessen, Ihrer Webseite den tragbaren Webclient Virtual Agent hinzuzufügen. Es reduziert die Codekomplexität und ist einfacher zu implementieren. Sie enthält auch Standard-Chatfunktionen, z. B. Klickaktionen zum Starten oder Schließen des Chats. Details finden Sie unter Fügen Sie das Chat-Widget Virtual Agent einer Drittpartei-Website hinzu.
    • Im iframe geben Sie die URL der einzubettenden Instanz an. Wenn Sie das Chat-Widget auf einer Seite einbetten, die sich nicht in Ihrer Instanz ServiceNow befindet, muss die URL eine anwenderdefinierte Instanz-URL sein. Aufgrund der erhöhten Browsersicherheit kann das Chat-Widget möglicherweise nicht geladen werden, wenn Sie keine anwenderdefinierte URL verwenden. Weitere Informationen zur Verwendung von anwenderdefinierten URLs finden Sie unter Ihrer Instanz anwenderdefinierte URLs zuordnen.
      Um eine anwenderdefinierte URL zu verwenden, gehen Sie wie folgt vor:
      Hinweis:
      Das Chat-Widget Virtual Agent funktioniert standardmäßig nicht über einen IFrame in Safari. Apple blockiert ursprungsübergreifende IFrames (wenn die Domäne der im IFrame verwendeten URL nicht mit der Domäne der Website selbst übereinstimmt).

    • Nachdem Sie den Virtual Agent-Client eingebettet haben, können Sie die SSO-Authentifizierung optional über das Chat-Widget auslösen, jedoch nur, wenn Ihre Instanz für die Verwendung eines externen SSO-Anbieters eingerichtet ist. Außerdem muss die Host Website denselben SSO-Provider wie Ihre Instanz verwenden. Weitere Informationen zum Festlegen von SSO-Anbietern finden Sie unter Externes Single Sign-on (SSO).

      Zum Auslösen der SSO-Authentifizierung erstellen Sie ein JavaScript-Skript, das Bedingungen für die Ausführung der Authentifizierung definiert und Anwender zu einer von Ihnen angegebenen Chat-Widget-Seite umleitet (siehe Schritt 2 unten). Sie geben auch die zulässigen URLs an, die in diesem Skript übergeben werden können, indem Sie sie in der Systemeigenschaft com.glide.cs.web_client_login_redirect_urls angeben. Geben Sie die vollständigen Umleitungs-URLs oder den Host-Teil der URL an, z. B. https://beispiel.com.

    Erforderliche Rolle: Administrator

    Warum und wann dieser Vorgang ausgeführt wird

    Dieses Verfahren erfordert, dass Sie Werte für die folgenden beiden Systemeigenschaften festlegen:
    • com.glide.cs.embed.csp_frame_ancestors
    • com.glide.cs.embed.xframe_options
    Diese Eigenschaften bestimmen die Sicherheitsrichtlinie für das eingebettete Chat-Widget, insbesondere wie Browser HTML-Inhalte für den Chat Virtual Agent und Servicemitarbeiter in einem IFrame rendern und sichern, bevor Sie den Webchat-Client einbetten.
    Um eine SSO-Authentifizierung für Ihre Gastanwender zu generieren, können Sie ein Skript erstellen, das die window.postMessage()- Methode (Web API) verwendet, um die Authentifizierung auszulösen und die URL anzugeben, an die Anwender nach der Authentifizierung weitergeleitet werden. Weitere Informationen zu dieser Methode und zu Windows-Objekten finden Sie unter Window.postMessage().
    Hinweis:
    Wenn Sie die Anwendung Content Management System (CMS) verwenden, um anwenderdefinierte Schnittstellen für die Anwendungen Now Platform und ServiceNow® zu erstellen, beachten Sie, dass Virtual Agentnicht unterstützt wird.

    Prozedur

    1. Legen Sie die Systemeigenschaft com.glide.cs.embed.csp_frame_ancestors und com.glide.cs.embed.xframe_options fest, um die HTTP-Header-Richtlinien zum Sichern der IFrame-Inhalte anzugeben.
      Die HTTP-Header-Richtlinien teilen dem Browser mit, ob eine Seite in bestimmten Domänen eingebettet werden kann, um Clickjacking-Versuche zu minimieren. Durch das Festlegen beider Eigenschaften wird sichergestellt, dass Sicherheitsrichtlinien für wichtige Browser und auch für ältere Browser wie Internet Explorer vorhanden sind.
      1. Geben Sie im Navigationsfilter sys_properties.list ein.
      2. Suchen Sie in der Tabelle „Systemeigenschaft“ [sys_properties] anhand des Namens nach der Eigenschaft com.glide.cs.embed.csp_frame_ancestors.
        Hinweis:
        Diese Eigenschaft legt den Quellwert der HTTP-Header-Richtlinie fest: Content-Security-Policy:frame-ancestors<source>. Verwenden Sie den Wert der Hostquelle, um die Domänen anzugeben, in die die externe Webseite eingebettet werden kann. Diese Eigenschaft gilt für die meisten gängigen Browser mit Ausnahme von Internet Explorer.
      3. Klicken Sie auf den Namen der Eigenschaft, um das Formular zu öffnen und die Richtlinienwerte anzugeben.
        Tabelle : 1. Systemeigenschaft: com.glide.cs.embed.csp_frame_ancestors
        Feld Beschreibung
        Typ Zeichenfolge

        Dies ist der Standardwert.
        Wert Geben Sie eine oder mehrere Quellen an, einschließlich:
        • „self“: Gibt an, dass der Ursprung mit der bereitgestellten Seite identisch ist. Beispiel: Wenn der Wert 'self' http://mywebsite.comlautet, ist der IFrame in die übergeordnete Domäne sowie in mywebsite.com eingebettet. Dies ist der Standardwert.
        • host-source: Die Domänen, in die die externe Webseite eingebettet werden kann. Geben Sie die Internet-Hostwebsite anhand des Namens, der IP-Adresse oder optional der URL und/oder Portnummer an. Die Site-Adresse kann mit einem Platzhalterzeichen (Sternchen) beginnen. Beispielwert: http://*.example.com
        • schema-source: Ein Schema. Beispiel: http: oder https:
        • keine: Keine übereinstimmenden URLs.

        Weitere Informationen zu Quellwerten, die Sie angeben können, finden Sie unter CSP:frame-ancestors und Sicherheitsrichtlinie für eingebettete Client-Inhalte von Virtual Agent (Härtung der Instanzsicherheit) in Hardening settings.

      4. Kehren Sie zur Tabelle „Systemeigenschaft“ [sys_properties] zurück, um anhand des Namens nach der Eigenschaft com.glide.cs.embed.xframe_options zu suchen.
        Hinweis:
        Diese Eigenschaft legt den Wert der Header-Richtlinie „X-Frame-Options“ fest, um anzugeben, ob der Browser eine externe Webseite in einem Frame rendern kann. Verwenden Sie den Standardwert für „sameorigin“, um die Domänen anzugeben, in die die externe Webseite eingebettet werden kann. Diese Eigenschaft gilt für ältere Browser wie Internet Explorer 11.
      5. Klicken Sie auf den Namen der Eigenschaft, um das Formular zu öffnen und die Richtlinienwerte anzugeben.
        Tabelle : 2. Systemeigenschaft: com.glide.cs.embed.xframe_options
        Feld Beschreibung
        Typ Zeichenfolge Standardwert
        Wert Geben Sie einen Wert an, einschließlich:
        • gleichen Ursprungs. Standardwert Zeigt die Seite in einem Frame an, der denselben Ursprung hat wie die Seite selbst. Beispielwert: allow from https://example.com.
        • verweigern. Zeigt die Seite nicht in einem Frame an.
        • allow-from-URI Zeigt die Seite nur in einem Frame am angegebenen Ursprung an.
          Hinweis:
          Dieser Wert funktioniert in modernen Browsern nicht mehr.

        Weitere Informationen zu Quellwerten, die Sie angeben können, finden Sie unter X-Frame-Options und Set Xframe options to prevent embedding third-party websites [Updated in Security Center 1.3] in Hardening settings.

    2. Nachdem Sie Ihre ServiceNow-Instanz einer anwenderdefinierten URL zugeordnet haben, erstellen Sie das iframe-Element, und geben Sie die anwenderdefinierte URL im Inline-Element (iframe) an, das zum Einbetten des Clients Virtual Agent in eine externe Webseite verwendet wird: "https:// <your-domain> .com/sn_va_web_client_app_embed.do
      Hinweis:
      Ihre Instanz kann mehrere anwenderdefinierte URLs haben, aber nur eine Instanz-URL. Sie dürfen nur Ihre anwenderdefinierte Instanz-URL verwenden.
      Zum Beispiel:
      <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>
      Hinweis:
      Geben Sie den Parameter ?sysparm_skip_load_history=true am Ende der URL an, um die Schnittstelle ohne Konversationsverlauf zu laden.
    3. Wahlweise: Erstellen Sie ein JavaScript-Skript, das die window.postMessage() -Methode (Web API) verwendet, um Ereignisbedingungen zu definieren, die die SSO-Authentifizierung auf einer Anwenderoberflächenseite auslösen und Anwender an eine von Ihnen angegebene Chat-Widget-Seite zurückleiten.
      Um Anwender zu einer Chat-Widget-Seite umzuleiten, verwenden Sie diese Zeichenfolge: "https://<your-instance> .service-now.com/sn_va_web_client_login.do?sysparm_redirect_uri=' + encodeURIComponent(<your-page> )
      Hinweis:
      Bevor Sie das Skript ausführen, verwenden Sie die Systemeigenschaft com.glide.cs.web_client_login_redirect_urls, um die URLs anzugeben, die im Skript übergeben werden können. Die Umleitung funktioniert nur, wenn Sie eine oder mehrere zulässige URLs im Eigenschaftswert angeben. Geben Sie die vollständigen Umleitungs-URLs oder den Host-Teil der URL an, z. B. https://beispiel.com.
      Beispielskript:
      <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>

      In diesem Beispiel wird die Authentifizierung in der angegebenen Instanz ausgelöst, wenn die Ereignisse SESSION_CREATED oder SESSION_LOGGED_OUT auftreten. Nach der Authentifizierung (wenn die SSO-Anmeldeinformationen für Anwender akzeptiert werden) werden Anwender zur eingebetteten Chat-Widget-Seite weitergeleitet, die Sie in sn_va-web_client_login.do?sysparm_redirect_uri=' + encodeURIComponent(<your-page> ) , sofern Sie auch die Seiten-URL in der Eigenschaft com.glide.cs.web_client_login_redirect_urls angegeben haben.