Incorporar o. Virtual Agent widget de bate-papo em uma página da web externa (método legado)

  • Versão de lançamento: Australia
  • Atualizado 12 de mar. de 2026
  • 6 min. de leitura

    • Carregue o. Virtual Agent interface do widget de bate-papo 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 de login único (SSO) para ser executado automaticamente para usuários convidados que estão usando o widget de bate-papo e não estão conectados.

    Antes de Iniciar

    Importante:
    Considere adicionar o Portátil Virtual Agent Em vez disso, o cliente da web para sua página da web. Isso 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 Adicione o portátil Virtual Agent widget de bate-papo para um site de terceiros.
    • No iframe, especifique o URL da instância a ser incorporada. Se você estiver incorporando o widget de bate-papo em qualquer página que não esteja no seu ServiceNow A URL deve ser uma URL de instância personalizada. Devido ao aumento da segurança do navegador, o widget de bate-papo 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 um URL personalizado, faça o seguinte:
      Nota:
      . Virtual Agent Por padrão, o widget de bate-papo não funciona em um iframe no Safari. 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 acionar a autenticação SSO do widget de bate-papo, 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 que sua instância. Para obter detalhes sobre como configurar provedores de SSO, consulte Single Sign-on externo (SSO) .

      Para acionar a autenticação SSO, crie um script JavaScript que define as condições para executar a autenticação e redireciona os usuários para uma página de widget de bate-papo especificada (consulte a Etapa 2 abaixo). Você também especifica os URLs permitidos que podem ser passados neste script, identificando-os no com.glide.cs.web_client_login_redirect_urlspropriedade do sistema. 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 do widget de bate-papo incorporado, ou seja, como os navegadores renderizam e protegem o conteúdo HTML para Virtual Agent e. Atendente bate-papo, em um iframe, antes de incorporar o cliente de bate-papo da web.
    Para gerar autenticação SSO para seus usuários convidados, você pode criar um script que usa o. Janela.postMessage() Método (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 Janela.postMessage() .
    Nota:
    Se você estiver usando a aplicação Sistema de gestão de conteúdo (CMS) para criar interfaces personalizadas para o. ServiceNow AI Platform e. ServiceNow® aplicações, esteja ciente de que ele não oferece suporte Virtual Agent.

    Procedimento

    1. Defina ambos com.glide.cs.embed.csp_frame_ancestorse. com.glide.cs.embed.xframe_optionsPropriedades do sistema 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 as tentativas de ClickJacking. A definição de ambas as 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 Propriedade do sistema [sys_properties], pesquise por com.glide.cs.embed.csp_frame_ancestorspropriedade por nome.
        Nota:
        Esta propriedade define o valor de origem da diretiva de cabeçalho HTTP: Content-Security-Policy:frame-Ancestors <source>. Use o. origem do host valor para especificar os domínios nos quais a página da web externa pode ser incorporada. Esta propriedade se aplica à maioria dos navegadores principais, exceto ao 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 origens, incluindo:
        • "autom" : Indica que a origem é a mesma da página que está sendo veiculada. Por exemplo, se o valor for 'self' http://mywebsite.com, em seguida, o iframe é incorporado ao domínio primário, bem como ao mywebsite.com. Este é o valor padrão.
        • origem do host : Os domínios nos quais a página da web externa pode ser incorporada. Especifique o site do host da Internet por nome, endereço IP ou URL opcional e/ou número de porta. O endereço do site pode começar com um caractere curinga (asterisco). Valor de exemplo: http://*.example.com
        • origem do esquema : Um esquema. Por exemplo: http: ou https:
        • nenhum : Não há URLs correspondentes.

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

      4. Retorne à tabela Propriedade do sistema [sys_properties] para pesquisar com.glide.cs.embed.xframe_optionspropriedade por nome.
        Nota:
        Esta 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 padrão mesoorigem valor 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:
        • mesoorigem . Valor padrão. Exibe a página em um quadro que tem a mesma origem da própria página. Valor de exemplo: Permitir de https://example.com.
        • negar . Não exibe a página em um quadro.
        • uri de permissão . 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-Opções e. Set Xframe options to prevent embedding third-party websites em Hardening settings.

    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. Virtual Agent cliente 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 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. "sysparm_skip_load_history Parâmetro no final do URL para carregar a interface sem o histórico da conversa.
    3. Opcional: Crie um script JavaScript que use o. Janela.postMessage() Método (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 de widget de bate-papo especificada por você.
      Para redirecionar usuários para uma página de widget de bate-papo, use esta cadeia de caracteres: "https://<your-instance>.service-now.com/sn_va_web_client_login.do?sysparm_redirect_uri=’ e encodeURIComponent(<your-page>)
      Nota:
      Antes de executar o script, use o. com.glide.cs.web_client_login_redirect_urlsPropriedade do sistema 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 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>

      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 widget de bate-papo incorporado que você especificou em <your-page> , Desde que você também tenha especificado o URL da página no com.glide.cs.web_client_login_redirect_urlspropriedade.