Incorporer le widget de messagerie Agent virtuel instantanée dans une page Web externe (méthode héritée)

Interfaces conversationnelles Yokohama

Release

yokohama

ft:locale

fr-FR

ft:publication_title

Interfaces conversationnelles Yokohama

ft:clusterId

convint

bundleId

convint

workflow

Platform

Incorporer le widget de messagerie Agent virtuel instantanée dans une page Web externe (méthode héritée)

Rversion finale: Yokohama

Mis à jour 30 janv. 2025

6 minutes de lecture

Chargez l’interface du widget de messagerie instantanée Agent virtuel dans une page Web externe à l’aide d’un élément de cadre en ligne (iframe). Vous pouvez également activer facultativement le processus d’authentification Single Sign-On (SSO) pour qu’il s’exécute automatiquement pour les utilisateurs invités qui utilisent le widget de messagerie instantanée et qui ne sont pas connectés.

Avant de commencer

Important :

Envisagez d’ajouter le client Web portable Agent virtuel à votre page Web à la place. Il réduit la complexité du code et est plus facile à mettre en œuvre. Il comprend également des fonctionnalités de chat standard, telles que des actions de clic pour lancer ou fermer le chat. Pour plus de détails, voir Ajouter le widget de messagerie instantanée portable Agent virtuel à un site web tiers.

Dans l’iframe, vous spécifiez l’URL de l’instance à intégrer. Si vous intégrez le widget de messagerie instantanée sur une page qui ne fait pas partie de votre ServiceNow instance, l’URL doit être une URL d’instance personnalisée. En raison de la sécurité accrue du navigateur, le widget de messagerie instantanée peut ne pas se charger si vous n’utilisez pas d’URL personnalisée. Pour en savoir plus sur l’utilisation des URL personnalisées, consultez Associer des URL personnalisées à votre instance.
Pour utiliser une URL personnalisée, procédez comme suit :
- Activez le module d’extension URL personnalisée (com.snc.customurl) dans votre instance.
- Ajoutez l’URL personnalisée (que vous avez précédemment achetée et enregistrée) à votre instance.
Remarque :
Par défaut, le Agent virtuel widget de messagerie instantanée ne fonctionne pas à partir d’un iframe dans Safari. Apple Bloque les iframes d’origine croisée (lorsque le domaine de l’URL utilisé dans l’iframe ne correspond pas au domaine du site web lui-même).
Après avoir incorporé le client Agent virtuel, vous pouvez éventuellement déclencher l’authentification SSO à partir du widget de messagerie instantanée, mais uniquement lorsque votre instance est configurée pour utiliser un fournisseur SSO externe. Votre site d’hébergement doit également utiliser le même fournisseur SSO que votre instance. Pour plus d’informations sur la définition des fournisseurs SSO, consultez Authentification unique (SSO) externe.

Pour déclencher l’authentification SSO, vous devez créer un script JavaScript qui définit les conditions d’exécution de l’authentification et redirige les utilisateurs vers une page de widget de messagerie instantanée que vous spécifiez (voir l’étape 2 ci-dessous). Vous spécifiez également les URL autorisées qui peuvent être transmises dans ce script, en les identifiant dans la com.glide.cs.web_client_login_redirect_urls propriété système. Spécifiez les URL de redirection complètes ou la partie hôte de l’URL, telle que https://example.com .

Rôle requis : admin

Pourquoi et quand exécuter cette tâche

Cette procédure nécessite que vous définissiez des valeurs pour les deux propriétés système suivantes :

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

Ces propriétés déterminent la politique de sécurité du widget de messagerie instantanée intégré, à savoir la façon dont les navigateurs affichent et sécurisent le contenu Agent virtuel HTML et Agent actif la messagerie instantanée, dans un iframe, avant d’incorporer le client de messagerie instantanée Web.

Pour générer une authentification SSO pour vos utilisateurs invités, vous pouvez créer un script qui utilise la méthode window.postMessage() (API Web) pour déclencher l’authentification et spécifier l’URL vers laquelle les utilisateurs sont redirigés après l’authentification. Pour plus d’informations sur cette méthode et les objets Window, consultez Window.postMessage().

Remarque :

Si vous utilisez l’application CMS (Content Management System) pour créer des interfaces personnalisées pour les Now Platform applications and ServiceNow® , sachez qu’elle ne prend pas en charge Agent virtuel.

Procédure

Définissez les com.glide.cs.embed.csp_frame_ancestors propriétés système et com.glide.cs.embed.xframe_options pour spécifier les directives d’en-tête HTTP afin de sécuriser le contenu iframe.

Les directives d’en-tête HTTP indiquent au navigateur si une page peut être incorporée sur certains domaines pour atténuer les tentatives de détournement de clic. La définition des deux propriétés garantit l’existence de directives de sécurité pour les principaux navigateurs ainsi que pour les navigateurs plus anciens, tels qu’Internet Explorer.

Dans le filtre de navigation, saisissez sys_properties.list.
Dans la table Propriétés système [sys_properties], recherchez la com.glide.cs.embed.csp_frame_ancestors propriété par nom.

Remarque :
Cette propriété définit la valeur source de la directive d’en-tête HTTP : Content-Security-Policy :frame-ancestors<source>. Utilisez la valeur hôte-source pour spécifier les domaines dans lesquels la page Web externe peut être incorporée. Cette propriété s’applique à la plupart des principaux navigateurs, à l’exception d’Internet Explorer.

Cliquez sur le nom de la propriété pour ouvrir le formulaire et spécifier les valeurs de directives.

Tableau 1. Propriété système : com.glide.cs.embed.csp_frame_ancestors
Champ	Description
Type	chaîne Il s’agit de la valeur par défaut.
Valeur	Spécifiez une ou plusieurs sources, notamment : 'self' : indique que l’origine est la même que la page servie. Par exemple, si la valeur est 'self' http://mywebsite.com, alors l’iframe est incorporé dans le domaine parent ainsi que mywebsite.com. Il s’agit de la valeur par défaut. host-source : les domaines dans lesquels la page Web externe peut être incorporée. Spécifiez le site hôte Internet par nom, adresse IP ou URL et/ou numéro de port en option. L’adresse du site peut commencer par un caractère générique (astérisque). Exemple de valeur : http ://*.example.com scheme-source : schéma A. Par exemple : http : ou https : aucune : aucune URL correspondante.

Pour plus d’informations sur les valeurs source que vous pouvez spécifier, consultez CSP :frame-ancestors et Politique de sécurité du contenu client intégré Virtual Agent (sécurisation renforcée de la sécurité de l’instance) dans Hardening settings.

Revenez à la table Propriétés système [sys_properties] pour rechercher la com.glide.cs.embed.xframe_options propriété par nom.

Remarque :
Cette propriété définit la valeur de la directive d’en-tête X-Frame-Options, pour indiquer si le navigateur peut afficher une page Web externe dans un cadre. Utilisez la valeur sameorigin par défaut pour spécifier les domaines dans lesquels la page Web externe peut être incorporée. Cette propriété s’applique aux navigateurs plus anciens, tels qu’Internet Explorer 11.

Cliquez sur le nom de la propriété pour ouvrir le formulaire et spécifier les valeurs de directives.

Tableau 2. Propriété système : com.glide.cs.embed.xframe_options
Champ	Description
Type	corde. Valeur par défaut.
Valeur	Spécifiez une valeur, notamment : `même origine`. Valeur par défaut. Affiche la page dans un cadre ayant la même origine que la page elle-même. Exemple de valeur : autoriser à partir de https://example.com. `nier`. N’affiche pas la page dans un cadre. `URI allow-from`. Affiche la page uniquement dans un cadre sur l’origine spécifiée. Remarque : Cette valeur ne fonctionne plus dans les navigateurs modernes.

Pour plus d’informations sur les valeurs source que vous pouvez spécifier, reportez-vous aux sections Options X-Frame et Set Xframe options to prevent embedding third-party websites [Updated in Security Center 1.3] à .Hardening settings

Après avoir associé votre instance ServiceNow à une URL personnalisée, créez l’élément iframe et spécifiez l’URL personnalisée dans l’élément en ligne (iframe) utilisé pour intégrer le Agent virtuel client dans une page Web externe : « https://<votre-domaine>.com/sn_va_web_client_app_embed.do »
Remarque :
Votre instance peut avoir plusieurs URL personnalisées, mais une seule URL d’instance. Vous ne devez utiliser que l’URL de votre instance personnalisée.
Par exemple :
```
<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>
```
Remarque :
Utilisez le paramètre ?sysparm_skip_load_history=true à la fin de l’URL pour charger l’interface sans l’historique de la conversation.
Facultatif : Créez un script JavaScript qui utilise la méthode window.postMessage() (API Web) pour définir les conditions d’événement qui déclenchent l’authentification SSO dans une page d’interface utilisateur et renvoie les utilisateurs à une page de widget de messagerie instantanée que vous spécifiez.
Pour rediriger les utilisateurs vers une page de widget de messagerie instantanée, utilisez cette chaîne : « https://<votre-instance>.service-now.com/sn_va_web_client_login.do?sysparm_redirect_uri=' + encodeURIComponent(<votre-page>)
Remarque :
Avant d’exécuter le script, utilisez la com.glide.cs.web_client_login_redirect_urls propriété système pour spécifier les URL qui peuvent être transmises dans le script. La redirection fonctionne uniquement lorsque vous spécifiez une ou plusieurs URL autorisées dans la valeur de la propriété. Spécifiez les URL de redirection complètes ou la partie hôte de l’URL, telle que https://example.com .
Exemple de script :
```
<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>
```
Dans cet exemple, l’authentification est déclenchée dans l’instance spécifiée lorsque des événements SESSION_CREATED ou SESSION_LOGGED_OUT se produisent. Après l’authentification (lorsque les informations d’identification SSO des utilisateurs sont acceptées), les utilisateurs sont redirigés vers la page du widget de messagerie instantanée incorporé que vous avez spécifiée dans sn_va-web_client_login.do ?sysparm_redirect_uri=' + encodeURIComponent(<votre-page>), à condition que vous ayez également spécifié l’URL de la page dans la com.glide.cs.web_client_login_redirect_urls propriété.