Incorporar o cliente web Virtual Agent em uma página da web externa (método legado)

  • Versão de lançamento: Xanadu
  • Atualizado 1 de ago. de 2024
  • 6 min. de leitura

    • Carregue a interface do cliente web Virtual Agent em uma página da web externa usando um elemento de quadro em linha (iframe). Opcionalmente, você também pode habilitar o processo de autenticação Single Sign-on (SSO) para ser executado automaticamente para usuários convidados que estão usando o cliente web e não estão conectados.

    Antes de Iniciar

    Importante:
    Considere adicionar o cliente web Virtual Agent portátil à sua página da web. Ele reduz a complexidade do código e é mais fácil de implementar. Ele também inclui recursos de bate-papo padrão, como ações de clique para iniciar ou fechar o bate-papo. Para obter detalhes, consulte Adicionar o cliente web Virtual Agent portátil a um site de terceiros.
    • No iframe, você especifica o URL da instância a ser incorporada. Se você estiver incorporando o cliente web em qualquer página que não esteja em sua instância ServiceNow, o URL deve ser um URL de instância personalizada. Devido ao aumento da segurança do navegador, o cliente web pode falhar ao carregar se você não usar um URL personalizado. Para saber mais sobre como usar URLs personalizados, consulte Associação de URLs personalizados à sua instância.
      Para usar uma URL personalizada, faça o seguinte:
      Nota:
      O cliente web Virtual Agent não funciona a partir de um iframe no Safari por padrão. Apple bloqueia iframes de origem cruzada (quando o domínio do URL usado no iframe não corresponde ao domínio do próprio site).

    • Depois de incorporar o cliente do Virtual Agent, você pode, opcionalmente, acionar a autenticação SSO do cliente web, mas somente quando sua instância estiver configurada para usar um provedor SSO externo. Seu site de hospedagem também deve usar o mesmo provedor de SSO da sua instância. Para obter detalhes sobre como definir provedores de SSO, consulte SSO (Single sign-on) externo.

      Para acionar a autenticação SSO, crie um script JavaScript que defina as condições para executar a autenticação e redirecione os usuários para uma página do cliente web que você especificar (veja a etapa 2 abaixo). Você também especifica os URLs permitidos que podem ser passados neste script, identificando-os na propriedade do sistema com.glide.cs.web_client_login_redirect_urls. Especifique os URLs de redirecionamento completos ou a parte do host do URL, como https://example.com .

    Função necessária: administrador

    Por Que e Quando Desempenhar Esta Tarefa

    Este procedimento requer que você defina valores para as duas propriedades do sistema a seguir:
    • com.glide.cs.embed.csp_frame_ancestors
    • com.glide.cs.embed.xframe_options
    Essas propriedades determinam a política de segurança para o cliente da web incorporado, ou seja, como os navegadores renderizam e protegem o conteúdo HTML para bate-papo Virtual Agent e Atendente, em um iframe, antes de incorporar o cliente de bate-papo da web.
    Para gerar autenticação SSO para usuários convidados, você pode criar um script que usa o método window.postMessage () (API da web) para acionar a autenticação e especificar o URL para onde os usuários são redirecionados após a autenticação. Para obter mais informações sobre este método e objetos de janela, consulte Window.postMessage ().
    Nota:
    Se você estiver usando a aplicação Sistema de gestão de conteúdo (CMS) para criar interfaces personalizadas para as aplicações Now Platform e ServiceNow®, lembre-se de que ele não é compatível com Virtual Agent.

    Procedimento

    1. Defina as propriedades do sistema com.glide.cs.embed.csp_frame_ancestors e com.glide.cs.embed.xframe_options para especificar as diretivas de cabeçalho HTTP para proteger o conteúdo do iframe.
      As diretivas de cabeçalho HTTP informam ao navegador se uma página pode ser incorporada em determinados domínios para mitigar tentativas de clickjacking. A definição das duas propriedades garante que haja diretivas de segurança para os principais navegadores e também para navegadores mais antigos, como o Internet Explorer.
      1. No filtro de navegação, insira sys_properties.list.
      2. Na tabela Propriedades do sistema [sys_properties], pesquise a propriedade com.glide.cs.embed.csp_frame_ancestors pelo nome.
        Nota:
        Esta propriedade define o valor de origem da diretiva de cabeçalho HTTP: Content-Security-Policy: frame-ancestors<source>. Use o valor do host-source para especificar os domínios nos quais a página da web externa pode ser incorporada. Esta propriedade se aplica à maioria dos principais navegadores, exceto para o Internet Explorer.
      3. Clique no nome da propriedade para abrir o formulário e especificar os valores da diretiva.
        Tabela 1. Propriedade do sistema: com.glide.cs.embed.csp_frame_ancestors
        Campo Descrição
        Tipo Cadeia de caracteres

        Este é o valor padrão.
        Valor Especifique uma ou mais fontes, incluindo:
        • 'self': indica que a origem é a mesma da página que está sendo exibida. Por exemplo, se o valor for 'self' http://mywebsite.com, o iframe será incorporado ao domínio primário e também ao mywebsite.com. Este é o valor padrão.
        • host-source: os domínios nos quais a página da Web externa pode ser incorporada. Especifique o site de host da Internet por nome, endereço IP ou URL opcional e/ou número da porta. O endereço do site pode começar com um caractere curinga (asterisco). Valor de exemplo: http://*.example.com
        • scheme-source: um esquema. Por exemplo: http: ou https:
        • nenhum: nenhum URL correspondente.

        Para obter mais informações sobre valores de origem que você pode especificar, consulte CSP:frame-ancestors e Política de segurança de conteúdo do cliente incorporado do Virtual Agent (reforço de segurança da instância) em Configurações do reforço de segurança da instância.

      4. Retorne para a tabela Propriedades do sistema [sys_properties] para pesquisar a propriedade com.glide.cs.embed.xframe_options pelo nome.
        Nota:
        Essa propriedade define o valor da diretiva de cabeçalho X-Frame-Options, para indicar se o navegador pode renderizar uma página da web externa em um quadro. Use o valor padrão sameorigin para especificar os domínios nos quais a página da web externa pode ser incorporada. Esta propriedade se aplica a navegadores mais antigos, como o Internet Explorer 11.
      5. Clique no nome da propriedade para abrir o formulário e especificar os valores da diretiva.
        Tabela 2. Propriedade do sistema: com.glide.cs.embed.xframe_options
        Campo Descrição
        Tipo cadeia de caracteres. Valor padrão.
        Valor Especifique um valor, incluindo:
        • sameorigin. Valor padrão. Exibe a página em um quadro que tem a mesma origem da própria página. Valor de exemplo: allow from https://example.com.
        • deny. Não exibe a página em um quadro.
        • allow-from uri. Exibe a página somente em um quadro na origem especificada.
          Nota:
          Este valor não funciona mais em navegadores modernos.

        Para obter mais informações sobre valores de origem que você pode especificar, consulte X-Frame-Options e X-Frame-Options do cliente incorporado do Virtual Agent (reforço de segurança da instância) em Configurações do reforço de segurança da instância.

    2. Depois de associar sua instância da ServiceNow a um URL personalizado, crie o elemento iframe e especifique o URL personalizado no elemento em linha (iframe) usado para incorporar o cliente Virtual Agent em uma página da Web externa: "https://<your-domain>.com/sn_va_web_client_app_embed.do"
      Nota:
      Sua instância pode ter vários URLs personalizados, mas apenas um URL de instância. Você deve usar somente o URL da sua instância personalizada.
      Por exemplo:
      <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>
      Nota:
      Use o parâmetro ?sysparm_skip_load_history=true no final do URL para carregar a interface sem o histórico da conversa.
    3. Opcional: Crie um script do JavaScript que usa o método window.postMessage() (API da Web) para definir condições de evento que acionam a autenticação SSO em uma página de interface do usuário e retorna os usuários para uma página do cliente web que você especificar.
      Para redirecionar usuários para uma página de cliente web, use esta cadeia de caracteres: "https://<your-instance>.service-now.com/sn_va_web_client_login.do?sysparm_redirect_uri=’ + encodeURIComponent(<your-page>)
      Nota:
      Antes de executar o script, use a propriedade do sistema com.glide.cs.web_client_login_redirect_urls para especificar os URLs que podem ser passados no script. O redirecionamento funciona somente quando você especifica um ou mais URLs permitidos no valor da propriedade. Especifique os URLs de redirecionamento completos ou a parte do host do URL, como https://example.com.
      Script de exemplo:
      <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>

      Neste exemplo, a autenticação é acionada na instância especificada quando ocorrem os eventos SESSION_CREATED ou SESSION_LOGGED_OUT. Após a autenticação (quando as credenciais de SSO dos usuários são aceitas), os usuários são redirecionados para a página do cliente Web incorporado que você especificou em sn_va-web_client_login.do?sysparm_redirect_uri=’ + encodeURIComponent(<your-page>), contanto que você também tenha especificado o URL da página na propriedade com.glide.cs.web_client_login_redirect_urls.