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

  • Rversion finale: Washingtondc
  • Mis à jour 1 févr. 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 le processus d’authentification SSO (Single Sign-on) pour qu’il s’exécute automatiquement pour les utilisateurs invités qui utilisent le client Web et 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 inclut également des fonctionnalités de chat standard, telles que les 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).

    • Après avoir incorporé le client Virtual Agent, vous pouvez éventuellement 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 de 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, par exemple 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é pour le client Web incorporé, notamment la façon dont les navigateurs affichent et sécurisent le contenu HTML pour Agent virtuel la messagerie instantanée 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 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 Content Management System (CMS) pour créer des interfaces personnalisées pour les Now Platform applications et ServiceNow® , sachez qu’elle ne prend pas en charge Agent virtuel.

    Procédure

    1. Définissez les propriétés système com.glide.cs.embed.csp_frame_ancestors et com.glide.cs.embed.xframe_options afin de spécifier les directives d’en-tête HTTP pour sécuriser le contenu de l’iframe.
      Les directives d’en-tête HTTP indiquent au navigateur si une page peut être intégrée à 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 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 host-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.
      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 Spécifiez 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ée dans le domaine parent ainsi que dans 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 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 : ou https :
        • none : aucune URL correspondante.

        Pour plus d’informations sur les valeurs sources que vous pouvez spécifier, consultez CSP :frame-ancestors et la politique de sécurité du contenu client incorporé de Virtual Agent (renforcement de la sécurité de l’instance) dans 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 incorporé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 String. 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 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 sources que vous pouvez spécifier, consultez X-Frame-Options et X-Frame-Options du client incorporé de Virtual Agent (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 incorporer le Agent virtuel client dans une page Web externe : « https://&lt;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 utiliser uniquement votre URL d’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 de client Web, utilisez cette chaîne : « https://&lt;votre-instance>.service-now.com/sn_va_web_client_login.do?sysparm_redirect_uri=' + encodeURIComponent(&lt;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, par exemple 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 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(&lt;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é.