Publicado em: 31 de julho de 2025
O Chrome está lançando um novo teste de origem do Chrome 139 para a API Soft Navigations com que já estávamos testando. Esse teste de origem permite que os sites testem a API com usuários reais para fazer um teste de campo e enviar feedback à equipe do Chrome.
O que são navegações leves?
Uma navegação suave ocorre quando o JavaScript intercepta uma navegação (por exemplo, ao clicar em um link) e atualiza o conteúdo na página atual, em vez de carregar uma nova página. Depois, o URL é atualizado na barra de endereço (com um estado de histórico para permitir navegações suaves para frente e para trás). Para o usuário, elas parecem iguais às navegações convencionais, mas, para o navegador, a página ainda é a original.
Por que a API Soft Navigation é necessária
A API Soft Navigations é uma API proposta para permitir a detecção baseada em heurística das chamadas "navegações suaves", usadas por sites de aplicativos de página única (SPA, na sigla em inglês). Como não há navegação de página real em uma navegação suave, isso significa que determinadas ações que normalmente acontecem em uma navegação precisam ser gerenciadas manualmente pelo JavaScript. Algumas ações, como o gerenciamento do histórico de navegação, são possíveis com as APIs atuais. No entanto, outras ações, como medir as Core Web Vitals, não são possíveis para essas navegações.
A API Soft Navigation permite a observação de navegações suaves. Embora o JavaScript que inicia a navegação suave (normalmente uma estrutura JavaScript) saiba quando uma navegação ocorre, outros JavaScripts e o próprio navegador não sabem.
Core Web Vitals e SPAs
Um dos principais motivadores da API Soft Navigation é permitir a medição das Core Web Vitals para SPAs. As Core Web Vitals são medidas pelo navegador (para aparecer em ferramentas como o Chrome User Experience Report) e por bibliotecas JavaScript de monitoramento de usuários reais (RUM, na sigla em inglês).
Os frameworks JavaScript podem medir alguns aspectos das Core Web Vitals. Em especial, a Interaction to Next Paint (INP) e a mudança de layout cumulativa (CLS) são baseadas em primitivos (respectivamente, a API Event Timing e a API Layout Instability) que podem ser medidas em qualquer período para calcular as métricas INP e CLS. No entanto, outras métricas, como a Maior exibição de conteúdo (LCP), são emitidas apenas pelo navegador com base nas navegações de página e finalizadas após a interação.
Como a API Soft Navigation permite a medição das Core Web Vitals para SPAs
A primeira iteração da API Soft Navigation combinou a heurística de navegação suave com uma redefinição do LCP. Depois que ele é redefinido, o LCP pode ser reemitido para navegações suaves para uma nova renderização significativa de conteúdo, permitindo a medição dessa métrica para navegações suaves.
Essa iteração mais recente adota uma abordagem diferente e desacopla esses conceitos na API Soft Navigation e em uma nova entrada de desempenho da interação até a renderização de conteúdo. A entrada interaction-contentful-paint mede a "pintura de conteúdo" após as interações. Por enquanto, isso só é emitido para navegações suaves, mas abre outros casos de uso em potencial além do LCP se ativado para todas as interações.
A API também expandiu cada uma das entradas de performance largest-contentful-paint, interaction-contentful-paint, event-timing e layout-shift para incluir um identificador da navegação a que a entrada se refere. As entradas de performance são emitidas após o evento que estão medindo, geralmente durante o tempo ocioso. Isso significa que o URL geralmente terá mudado quando a entrada de performance for emitida. Incluir a navegação com a entrada facilita muito a medição das Core Web Vitals para o URL especificado sem precisar corresponder os tempos de entrada de performance aos tempos de entrada de navegação suave.
Por que uma heurística?
A API Soft Navigation considera uma navegação leve quando o seguinte ocorre:
- Ocorre uma interação baseada no usuário (atualizações de URL sem interação do usuário não são contabilizadas)
- … o que resulta em uma modificação do DOM e uma renderização.
- … e uma atualização de URL ocorre
- Atualização de URL, incluindo uma mudança no histórico.
A API usa essa abordagem baseada em heurística em vez de permitir que uma estrutura JavaScript "emita" uma navegação suave ou seja criada com base na API Navigation. Isso permite uma compreensão consistente do que constitui uma navegação suave, independente da estrutura ou de como um desenvolvedor a usa.
Os frameworks ou desenvolvedores podem atualizar o URL de uma navegação suave mesmo sem uma interação do usuário ou uma atualização do DOM que consideramos o que um usuário veria como uma navegação. Eles também podem atualizar o URL em momentos diferentes: no início da interação, apenas no final, quando ela estiver concluída, ou em qualquer estado intermediário.
Em vez de depender de escolhas de framework, a criação da detecção de navegação suave no navegador estabelece "heurísticas" canônicas (com seu feedback deste teste de origem) que nos permitirão medir as Core Web Vitals para navegações suaves em grande escala e tornar essas medições comparáveis em grande escala.
Os frameworks e desenvolvedores também podem ignorar as heurísticas da API Soft Navigations e usar as APIs Event Timing, Layout Instability e Interaction to Contentful Paint para medir outras métricas de desempenho como quiserem. No entanto, recomendamos o uso dos Core Web Vitals com a heurística para permitir a medição em vários sites.
Preciso de ajuda para testar a API Soft Navigation
Precisamos de ajuda para testar a API Soft Navigations e verificar se a heurística corresponde corretamente às suas expectativas de quando uma navegação suave ocorreu. Há casos em que a API não informa navegações leves quando você considera que elas ocorreram? Por outro lado, a API faz navegações repetidas que você não considera como navegações suaves?
Exemplos de problemas que encontramos: quando um URL é atualizado com replaceState em vez de adicionar um histórico ou quando ocorre uma navegação que não é iniciada pelo usuário (por exemplo, um logout por tempo limite). Ambos os casos são explicados por não corresponderem à heurística, e a equipe do Chrome não vê problemas em não incluir esses casos, mas queremos saber se os desenvolvedores da Web concordam. Queremos saber principalmente sobre casos em que as heurísticas parecem ser atendidas, mas a API ainda não reconhece a navegação suave.
Além disso, queremos entender se essa API e a nova primitiva Interaction to Contentful Paint atendem ao principal caso de uso de permitir a medição das Core Web Vitals para SPAs.
Queremos que a API seja o mais útil possível, e isso é muito mais fácil de acontecer antes do lançamento e de os sites começarem a depender de uma implementação. Portanto, pedimos aos desenvolvedores de SPAs e às pessoas interessadas em medir o desempenho da Web nesses sites que testem essa API e nos informem como ela funciona para você.
Como testar
A API pode ser testada localmente com flags do Chrome ou opções de linha de comando. Além disso, ele pode ser testado em campo com o teste de origem.
Consulte nossa documentação ou o repositório do GitHub para mais detalhes técnicos da API e, em particular, como medir as principais métricas da Web. Além disso, uma versão experimental de navegação suave da biblioteca web-vitals está disponível.
Feedback
Estamos buscando feedback sobre esse experimento nos seguintes lugares:
- O feedback sobre a API deve ser levantado como problemas no GitHub.
- Bugs na implementação do Chromium devem ser informados no rastreador de problemas do Chrome, se ainda não forem um dos problemas conhecidos.
- O feedback geral sobre as métricas vitais da Web pode ser compartilhado em web-vitals-feedback@googlegroups.com.
Se estiver em dúvida, não se preocupe muito. Preferimos receber o feedback em qualquer um dos lugares e vamos analisar os problemas nos dois locais e redirecioná-los para o local correto.