Incorporer le Agent virtuel client Web dans une page Web externe (méthode héritée)

  • Rversion finale: Xanadu
  • Mis à jour 1 août 2024
  • 6 minutes de lecture

    • Chargez l’interface Agent virtuel du client Web dans une page Web externe à l’aide d’un élément de cadre en ligne (iframe). Vous pouvez également activer de manière facultative l’exécution automatique du processus d’authentification SSO (Authentification unique) pour les utilisateurs invités qui utilisent le client Web et qui ne sont pas connectés.

    Avant de commencer

    Important :
    Envisagez plutôt d’ajouter le client Web portable Agent virtuel à votre page Web. 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 client Web portable Agent virtuel à un site Web tiers.
    • Dans l’iframe, vous spécifiez l’URL de l’instance à incorporer. Si vous incorporez le client Web sur une page qui ne se trouve pas sur votre ServiceNow instance, l’URL doit être une URL d’instance personnalisée. En raison de la sécurité accrue du navigateur, le client Web 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 :
      Remarque :
      Par défaut, le Agent virtuel client Web ne fonctionne pas à partir d’un iframe dans Safari. Apple bloque les iframes cross-origin (lorsque le domaine de l’URL utilisé dans l’iframe ne correspond pas au domaine du site web lui-même).

    • Une fois que vous avez incorporé le client Agent virtuel, vous pouvez déclencher l’authentification SSO à partir du client Web, 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 client Web 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 : administrateur

    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 client Web intégré, notamment la façon dont les navigateurs affichent et sécurisent le contenu Agent virtuel HTML pour et Agent actif la messagerie instantanée dans un iFrame avant que vous n’incorporiez le client de messagerie instantanée Web.
    Pour générer l’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 où les utilisateurs sont redirigés après 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

    1. 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 intégrée sur certains domaines afin d’atténuer les tentatives de détournement de clic. La définition des deux propriétés garantit qu’il existe des directives de sécurité pour les principaux navigateurs ainsi que pour les navigateurs plus anciens, tels qu’Internet Explorer.
      1. Dans le filtre de navigation, saisissez sys_properties.list.
      2. Dans la table Propriétés système [sys_properties], recherchez la com.glide.cs.embed.csp_frame_ancestors propriété par son 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 intégrée. Cette propriété s’applique à la plupart des principaux navigateurs, à l’exception d’Internet Explorer.
      3. Cliquez sur le nom de la propriété pour ouvrir le formulaire et spécifier les valeurs de la directive.
        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 Indiquez une ou plusieurs sources, notamment :
        • 'self' : indique que l’origine est la même que celle de la page diffusée. 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 intégrée. Spécifiez le site hôte Internet par nom, adresse IP ou URL et/ou numéro de port facultatif. L’adresse du site peut commencer par un caractère générique (astérisque). Exemple de valeur : http ://*.example.com
        • scheme-source : un schéma. Par exemple : http : ouhttps :
        • none : aucune URL correspondante.

        Pour plus d’informations sur les valeurs source que vous pouvez spécifier, consultez CSP :frame-ancestors et la politique de sécurité du contenu du client Virtual Agent incorporé (renforcement de la sécurité de l’instance) dans les paramètres de renforcement de la sécurité de l’instance.

      4. 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 intégrée. Cette propriété s’applique aux navigateurs plus anciens, tels qu’Internet Explorer 11.
      5. Cliquez sur le nom de la propriété pour ouvrir le formulaire et spécifier les valeurs de la directive.
        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, y compris :
        • sameOrigin. Valeur par défaut. Affiche la page dans un cadre qui a la même origine que la page elle-même. Exemple de valeur : autoriser à partir de https://example.com.
        • refuser. N’affiche pas la page dans un cadre.
        • URI d’autorisation. 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, consultez X-Frame-Options et X-Frame-Options du client intégré de l’agent virtuel (renforcement de la sécurité de l’instance) dans les paramètres de renforcement de la sécurité de l’instance.

    2. 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 devez uniquement utiliser 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.
    3. 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 renvoient les utilisateurs vers une page de client Web que vous spécifiez.
      Pour rediriger les utilisateurs vers une page client Web, 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 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>

      Dans cet exemple, l’authentification est déclenchée dans l’instance spécifiée lorsque les événements SESSION_CREATED ou SESSION_LOGGED_OUT se produisent. Après l’authentification (lorsque les informations d’identification SSO pour les utilisateurs sont acceptées), les utilisateurs sont redirigés vers la page du client Web incorporée 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é.