Publicado em: 31 de julho de 2025
O Chrome está lançando um novo teste de origem no Chrome 139 para a API Soft Navigations com que já estávamos trabalhando. Esse teste de origem permite que os sites testem a API no site com usuários reais para testar a API e fornecer feedback à equipe do Chrome.
O que são navegações leves?
Uma navegação leve ocorre quando o JavaScript intercepta uma navegação (por exemplo, clicar em um link) e atualiza o conteúdo na página atual, em vez de carregar uma nova página. Em seguida, o URL é atualizado na barra de endereço (com um estado de histórico para permitir navegações leves para trás e para frente). Para o usuário, elas parecem iguais às navegações convencionais, mas, no que diz respeito ao 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 heurística das chamadas "navegações leves" usadas por sites de aplicativos de página única (SPA, na sigla em inglês). Como nenhuma navegação nas páginas real acontece para uma navegação leve, isso significa que determinadas ações que normalmente ocorreriam para 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 a medição das Core Web Vitals, não são possíveis para essas navegações.
A API Soft Navigation permite a observação de navegações leves. Embora o framework de JavaScript que inicia a navegação leve (normalmente um framework de JavaScript) saiba quando uma navegação ocorre, outros JavaScripts e o próprio navegador não saberão.
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 Relatório de experiência do usuário do Chrome) e por bibliotecas JavaScript de monitoramento de usuários reais (RUM, na sigla em inglês).
As estruturas JavaScript podem medir alguns aspectos das Core Web Vitals. Em particular, a Interaction to Next Paint (INP) e a Cumulative Layout Shift (CLS) são baseadas em primitivos (a API Event Timing e a API Layout Instability, respectivamente) que podem ser medidas em qualquer período para calcular as métricas INP e CLS. No entanto, como o navegador informa e finaliza a Largest Contentful Paint (LCP) com base em navegações e interações de páginas, as estruturas JavaScript não têm visibilidade em nada além do desempenho de carregamento inicial para SPAs.
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 leve com uma redefinição da LCP. Depois de redefinida, a LCP pode ser reemitida para navegações leves para novas pinturas de conteúdo, permitindo a medição dessa métrica para navegações leves.
Essa iteração mais recente adota uma abordagem diferente e desvincula esses conceitos na API Soft Navigation e em uma nova entrada de desempenho da Interaction to Contentful Paint. A entrada interaction-contentful-paint mede a "pintura de conteúdo" após as interações. Por enquanto, isso só é emitido para navegações leves, mas abre outros casos de uso em potencial além da LCP se ativado para todas as interações.
A API também expandiu cada uma das entradas de desempenho largest-contentful-paint, interaction-contentful-paint, event-timing e layout-shift para incluir um identificador da navegação para a entrada. As entradas de desempenho são emitidas após o evento que estão medindo, geralmente durante o tempo de inatividade. Isso significa que o URL geralmente terá mudado quando a entrada de desempenho for emitida. Incluir a navegação com a entrada facilita muito a medição das Core Web Vitals para o URL especificado, sem precisar comparar os tempos de entrada de desempenho com os tempos de entrada de navegação leve.
Por que uma heurística?
A API Soft Navigation considera uma navegação leve quando ocorre o seguinte:
- Uma interação baseada no usuário ocorre (as atualizações de URL sem uma interação do usuário não são contabilizadas)
- … que resulta em uma modificação do DOM e uma pintura
- … e uma atualização de URL ocorre
- Atualização de URL, incluindo uma mudança de histórico.
A API adota essa abordagem heurística em vez de permitir que um framework de JavaScript "emita" uma navegação leve ou seja criada na API Navigation, porque isso permite uma compreensão consistente do que constitui uma navegação leve, independentemente do framework ou de como um desenvolvedor a usa.
As estruturas ou os desenvolvedores podem atualizar o URL de uma navegação leve 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 ou apenas no final, quando ela estiver concluída, ou em qualquer estado intermediário.
Em vez de depender das opções de estrutura, a criação da detecção de navegação leve no navegador estabelece "heurísticas" canônicas (com seu feedback desse teste de origem), o que nos permitirá medir as Core Web Vitals para navegações leves em escala e tornar essas medições comparáveis em escala.
As estruturas e os desenvolvedores também podem ignorar a heurística da API Soft Navigations e usar as APIs Event Timing, Layout Instability e Interaction to Contentful Paint subjacentes para medir outras métricas de desempenho como quiserem, mas recomendamos as Core Web Vitals usando a heurística para permitir a medição em todos os sites.
Ajuda necessária para testar a API Soft Navigation
Precisamos de ajuda para testar a API Soft Navigations para verificar se a heurística corresponde corretamente às suas expectativas de quando uma navegação leve ocorreu. Há instâncias em que a API não informa navegações leves quando você considera que elas ocorreram? Por outro lado, a API repete navegações que você não considera leves?
Exemplos que vimos causar problemas incluem 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 no tempo limite). Ambos os casos são explicados por não corresponderem à heurística, e a equipe do Chrome não se importa em não incluí-los, mas queremos saber se os desenvolvedores da Web concordam. E queremos saber sobre casos em que a heurística parece ser atendida, mas a API ainda não reconhece a navegação leve.
Além disso, queremos entender se essa API e o novo primitivo Interaction to Contentful Paint atendem ao caso de uso principal 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 dos sites começarem a depender de uma implementação. Portanto, pedimos aos desenvolvedores de SPA e aos interessados em medir o desempenho da Web desses 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, ela pode ser testada 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 Core Web Vitals. Além disso, uma versão experimental de navegação leve da biblioteca web-vitals está disponível.
Feedback
Estamos buscando ativamente feedback sobre esse experimento nos seguintes locais:
- O feedback sobre a API precisa ser levantado como problemas no GitHub.
- Os bugs na implementação do Chromium precisam ser levantados no Issue Tracker do Chrome, se ainda não forem um dos problemas conhecidos ainda.
- O feedback geral sobre as Core Web Vitals pode ser compartilhado em web-vitals-feedback@googlegroups.com.
Em caso de dúvida, não se preocupe muito. Preferimos receber o feedback em qualquer um dos locais e vamos classificar os problemas nos dois locais e redirecionar os problemas para o local correto.