Virtual Agent -Webclient in eine externe Webseite einbetten (veraltete Methode)

Freigeben Version: Washingtondc

Aktualisiert 1. Februar 2024

5 Minuten Lesedauer

Laden Sie die Webclient-Schnittstelle Virtual Agent auf einer externen Webseite mithilfe eines Inline-Frame-Elements (iframe). Optional können Sie auch den Prozess der SSO-Authentifizierung (Single Sign-on) aktivieren, der für Gastbenutzer, die den Webclient verwenden und nicht angemeldet sind, automatisch ausgeführt wird.

Vorbereitungen

Wichtig:

Erwägen Sie stattdessen, den tragbaren Virtual Agent Webclient zu Ihrer Webseite 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 den tragbaren Webclient Virtual Agent einer Drittanbieter-Website hinzu.

Im IFrame geben Sie die URL der einzubettenden Instanz an. Wenn Sie den Webclient auf einer Seite einbetten, die sich nicht in Ihrer ServiceNow -Instanz befindet, muss die URL eine benutzerdefinierte Instanz-URL sein. Aufgrund der erhöhten Browsersicherheit kann der Webclient möglicherweise nicht geladen werden, wenn Sie keine benutzerdefinierte URL verwenden. Weitere Informationen zur Verwendung von benutzerdefinierten URLs finden Sie unter Benutzerdefinierte URLs zu Ihrer Instanz zuordnen.
Gehen Sie wie folgt vor, um eine benutzerdefinierte URL zu verwenden:
- Aktivieren Sie das benutzerdefinierte URL-Plugin (com.snc.customurl) in Ihrer Instanz.
- Fügen Sie die benutzerdefinierte URL (die Sie zuvor erworben und registriert haben) zu Ihrer Instanz hinzu.
Hinweis:
Der Webclient Virtual Agent funktioniert standardmäßig nicht aus einem 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 optional die SSO-Authentifizierung über den Webclient auslösen, jedoch nur, wenn Ihre Instanz für die Verwendung eines externen SSO-Providers eingerichtet ist. Außerdem muss die Host Website denselben SSO-Provider wie Ihre Instanz verwenden. Weitere Informationen zum Festlegen von SSO-Providern finden Sie unter Externes Single Sign-on (SSO).

Um die SSO-Authentifizierung auszulösen, erstellen Sie ein JavaScript-Skript, das Bedingungen für die Ausführung der Authentifizierung definiert und Benutzer zu einer von Ihnen angegebenen Webclient-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://example.com.

Erforderliche Rolle: admin

Warum und wann dieser Vorgang ausgeführt wird

Für dieses Verfahren müssen 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 den eingebetteten Webclient, d. h. wie Browser HTML-Inhalte für Virtual Agent und Service Desk-Mitarbeiter Chat in einem IFrame rendern und sichern, bevor Sie den Webchat-Client einbetten.

Um die SSO-Authentifizierung für Ihre Gastbenutzer zu generieren, können Sie ein Skript erstellen, das die Methode window.postMessage() (Web-API) verwendet, um die Authentifizierung auszulösen, und die URL angeben, an die Benutzer 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 benutzerdefinierte Schnittstellen für die Anwendungen Now Platform und ServiceNow® zu erstellen, beachten Sie, dass sie Virtual Agentnicht unterstützt.

Prozedur

Legen Sie die Systemeigenschaften com.glide.cs.embed.csp_frame_ancestors und com.glide.cs.embed.xframe_options fest, um die HTTP-Header-Anweisungen zum Sichern des IFrame-Inhalts anzugeben.

Die HTTP-Header-Anweisungen teilen dem Browser mit, ob eine Seite in bestimmten Domänen eingebettet werden kann, um Clickjacking-Versuche abzuschwächen. Durch das Festlegen beider Eigenschaften wird sichergestellt, dass Sicherheitsrichtlinien für die wichtigsten Browser und auch für ältere Browser wie Internet Explorer vorhanden sind.

Geben Sie im Navigationsfilter sys_properties.list ein.
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-Direktive fest: Content-Security-Policy:frame-ancestors<source>. Verwenden Sie den Wert host-source, um die Domänen anzugeben, in denen die externe Webseite eingebettet werden kann. Diese Eigenschaft gilt für die meisten gängigen Browser mit Ausnahme von Internet Explorer.

Klicken Sie auf den Eigenschaftsnamen, um das Formular zu öffnen und die Anweisungswerte 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, wird 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-Host-Site nach Name, IP-Adresse oder optionaler URL und/oder Portnummer an. Die Site-Adresse kann mit einem Platzhalterzeichen (Sternchen) beginnen. Beispielwert: http://*.example.com scheme-source: ein Schema. Beispiel: http: oder https: none: keine übereinstimmenden URLs.

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

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-Direktive X-Frame-Options fest, um anzugeben, ob der Browser eine externe Webseite in einem Frame rendern kann. Verwenden Sie den Standardwert sameorigin, um die Domänen anzugeben, in denen die externe Webseite eingebettet werden kann. Diese Eigenschaft gilt für ältere Browser wie Internet Explorer 11.

Klicken Sie auf den Eigenschaftsnamen, um das Formular zu öffnen und die Anweisungswerte anzugeben.

Tabelle : 2. Systemeigenschaft: com.glide.cs.embed.xframe_options
Feld	Beschreibung
Typ	Zeichenfolge. Standardwert.
Wert	Geben Sie einen Wert an, einschließlich: `gleicher Ursprung`. Standardwert. Zeigt die Seite in einem Frame an, der denselben Ursprung wie die Seite hat. 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 in Virtual Agent eingebetteter Client X-Frame-Options (Härtung der Instanzsicherheit) in Einstellungen für die Härtung der Instanzsicherheit.

Nachdem Sie Ihre ServiceNow-Instanz einer benutzerdefinierten URL zugeordnet haben, erstellen Sie das iframe-Element, und geben Sie die benutzerdefinierte URL im Inline-Element (iframe) an, das zum Einbetten des Virtual Agent -Clients in eine externe Webseite verwendet wird: „https://“ <your-domain> .com/sn_va_web_client_app_embed.do“
Hinweis:
Ihre Instanz verfügt möglicherweise über mehrere benutzerdefinierte URLs, aber nur eine Instanz-URL. Sie dürfen nur Ihre benutzerdefinierte Instanz-URL verwenden.
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.
Wahlweise: Erstellen Sie ein JavaScript-Skript, das mithilfe der Methode window.postMessage() (Web-API) Ereignisbedingungen definiert, die die SSO-Authentifizierung in einer Benutzeroberflächenseite auslösen, und Benutzer an eine von Ihnen angegebene Webclient-Seite weiterleitet.
Verwenden Sie diese Zeichenfolge, um Benutzer zu einer Webclient-Seite umzuleiten: „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://example.com.
Beispielskript:
```
<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>
```
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 Benutzer akzeptiert werden) werden Benutzer zu der eingebetteten Webclientseite weitergeleitet, die Sie in sn_va-web_client_login.do?sysparm_redirect_uri=' + encodeURIComponent(<your-page> ) , solange Sie auch die Seiten-URL in der Eigenschaft com.glide.cs.web_client_login_redirect_urls angegeben haben.