Uma nova versão da API Reporting está disponível. Essa é uma interface mais privada e compatível com vários navegadores.
A API Reporting informa sobre erros que ocorrem em todo o seu site conforme os visitantes o utilizam. Ele oferece visibilidade sobre intervenções e falhas do navegador, violações da Política de Segurança de Conteúdo, violações COOP/COEP, avisos de descontinuação e muito mais.
Uma nova versão da API Reporting está disponível. A nova API é mais enxuta e provavelmente tem suporte em todos os navegadores.
Resumo
Desenvolvedores de sites
Se você já tiver a funcionalidade de geração de relatórios no seu site: migre para a v1 usando o novo cabeçalho
(Reporting-Endpoints
), mas mantenha o cabeçalho legado por algum tempo (Report-To
).
Consulte Migração: código de exemplo.
Se você estiver adicionando a funcionalidade de relatórios ao seu site agora há pouco: use somente o novo cabeçalho
(Reporting-Endpoints
).
⚠️ Em ambos os casos, defina o cabeçalho Reporting-Endpoints
em todas as respostas que possam
gerar relatórios.
Desenvolvedores de serviços de relatórios
Se você mantém um serviço de endpoint ou opera o seu próprio, espere mais tráfego à medida que você ou desenvolvedores externos migram para a API Reporting v1 (cabeçalho Reporting-Endpoints
).
Continue lendo para conferir detalhes e exemplos de código.
Geração de registros de erros de rede
Será desenvolvido um novo mecanismo para o registro de erros de rede. Quando ela estiver disponível, mude da API Reporting v0 para o novo mecanismo.
Demonstração e código
- Site de demonstração: nova API Reporting (v1)
- Código do site de demonstração
Diferenças entre as versões v0 e v1
O que muda?
- A plataforma da API é diferente.
Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] } Document-Policy: ...; report-to main-endpoint
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default" Document-Policy: ...; report-to main-endpoint
- O escopo do relatório é diferente.
Na v0, é possível definir endpoints de relatórios apenas em algumas respostas. Outros documentos (páginas) nessa origem usariam automaticamente esses endpoints de ambiente.
Com a v1, é necessário definir o cabeçalho Reporting-Endpoints
em todas as respostas que possam gerar relatórios.
- As duas APIs aceitam os mesmos tipos de relatório, com uma exceção: a v1 não é compatível com os relatórios de erros de rede. Leia mais nas etapas de migração.
- A v0 não é e não terá suporte em vários navegadores, e a v1 provavelmente será compatível com vários navegadores no futuro.
O que permanece inalterado
- O formato e a estrutura dos relatórios não foram alterados.
- A solicitação enviada pelo navegador para o endpoint continua sendo uma solicitação
POST
deContent-type
application/reports+json
. - O mapeamento de certos endpoints para determinados tipos de relatório é compatível com as versões v0 e v1.
- A função do endpoint
default
não muda. A API Reporting v1 não afeta o
ReportingObserver
. OReportingObserver
continua tendo acesso a todos os relatórios observáveis, e o formato dele é idêntico.
Todas as diferenças entre as versões v0 e v1
Cabeçalho da API Reporting legada (v0)Report-To |
Nova API Reporting (v1) Cabeçalho Reporting-Endpoints |
|
---|---|---|
Suporte ao navegador | Chrome 69 ou mais recente e Edge 69 ou mais recente. | Chrome 96+ e Edge 96+. O Firefox é compatível. O Safari não faz objeção. Consulte os indicadores do navegador. |
Endpoints | Envia relatórios para qualquer um dos vários coletores de relatório (vários URLs definidos por grupo de endpoints). | Envia relatórios para coletores de relatórios específicos (apenas um URL definido por endpoint). |
Superfície da API | Usa o cabeçalho `Report-To` para configurar grupos de endpoints nomeados. |
Usa o cabeçalho `Reporting-Endpoints` para configurar endpoints nomeados. |
Tipos de relatório que podem ser gerados por meio dessa API |
|
Sem mudanças, exceto no Registro de erros de rede (NEL, na sigla em inglês): não é compatível com a nova API Reporting (v1). |
Escopo do relatório | Origem. O cabeçalho Report-To de um documento afeta outros documentos (páginas) dessa origem.
O campo url de um relatório ainda varia de acordo com o documento.
|
Document. O cabeçalho Reporting-Endpoints de um documento só afeta esse documento.
O campo url de um relatório ainda varia de acordo com o documento.
|
Isolamento de relatórios (em lote) | Documentos (páginas) ou sites/origens diferentes que geram um relatório aproximadamente ao mesmo tempo e que têm o mesmo endpoint de relatórios são agrupados em lote: eles são enviados na mesma mensagem para esse endpoint. |
|
Suporte para balanceamento de carga / prioridades | Sim | No |
Desenvolvedores de endpoints: espera-se mais tráfego
Se você tiver configurado seu próprio servidor como um endpoint de relatórios ou se estiver desenvolvendo ou mantendo um coletor de relatórios como serviço, espere mais tráfego para esse endpoint.
Isso ocorre porque os relatórios não são agrupados na API Reporting v1 como na API Reporting v0. Portanto, à medida que os desenvolvedores de aplicativos migram para a API Reporting v1, o número de relatórios permanece semelhante, mas o volume de solicitações para o servidor de endpoint aumenta.
Desenvolvedores de aplicativos: migrar para o Reporting-Endpoints
(v1)
O que você deve fazer?
O uso da nova API Reporting (v1) tem vários benefícios ✅:
- Os sinais do navegador são positivos, o que significa que a compatibilidade entre navegadores é esperada para a v1 (ao contrário da v0, que só é compatível com o Chrome e o Edge).
- A API é mais enxuta.
- As ferramentas estão sendo desenvolvidas com base na nova API Reporting (v1).
Pensando nisso:
- Se o site já usa a API Reporting v0 com o cabeçalho
Report-To
, migre para a API Reporting v1. Consulte as etapas de migração. Se o site já usa o recurso de denúncia para violações da Política de Segurança de Conteúdo, confira as etapas de migração para relatórios da CSP. - Caso seu site ainda não use a API Reporting e você esteja adicionando a funcionalidade de relatórios, use a nova API Reporting (v1) (o cabeçalho
Reporting-Endpoints
). Há uma exceção a isso: se você precisar usar o Network Error Logging, useReport-To
(v0). No momento, o Network Error Logging não é compatível com a API Reporting v1. Um novo mecanismo para geração de registros de erros de rede será desenvolvido até que ele esteja disponível. Use a API Reporting v0. Se você precisar da geração de registros de erros de rede junto de outros tipos de relatório, use os doisReport-To
(v0) eReporting-Endpoints
(v1). A v0 fornece relatórios de erros de rede de todos os outros tipos.
Etapas de migração
Seu objetivo nesta migração é não perder os relatórios que costumava gerar com a v0.
Etapa 1 (faça agora): use os dois cabeçalhos
Report-To
(v0) eReporting-Endpoints
(v1).Com isso, você tem:
- Relatórios de clientes mais recentes do Chrome e do Edge graças ao
Reporting-Endpoints
(v1). - Relatórios de clientes mais antigos do Chrome e do Edge graças ao
Report-To
(v0).
As instâncias de navegador compatíveis com
Reporting-Endpoints
usarãoReporting-Endpoints
e as instâncias que não forem compatíveis serão substituídas porReport-To
. O formato da solicitação e do relatório é o mesmo para a v0 e a v1.- Relatórios de clientes mais recentes do Chrome e do Edge graças ao
Etapa 2 (faça agora): verifique se o cabeçalho
Reporting-Endpoints
está definido em todas as respostas que podem gerar relatórios.Na v0, você pode optar por definir endpoints de relatório apenas em algumas respostas, e outros documentos (páginas) nessa origem usariam esse endpoint "ambient". Na v1, devido à diferença no escopo, é necessário definir o cabeçalho
Reporting-Endpoints
em todas as respostas que podem gerar relatórios.Etapa 3 (começar mais tarde): quando todos ou a maioria dos usuários tiverem atualizado para instalações posteriores do Chrome ou do Edge (96 e mais recentes), remova
Report-To
(v0) e mantenha apenasReporting-Endpoints
.Uma exceção: se você precisar de relatórios de registro de erros de rede, mantenha
Report-To
até que um novo mecanismo esteja em vigor para o registro de erros de rede.
Confira exemplos de código no manual de migração.
Etapas de migração para relatórios de CSP
Há duas maneiras de configurar os relatórios de violação da Política de segurança de conteúdo:
- Com o cabeçalho da CSP usando a diretiva
report-uri
. Esse recurso tem suporte amplo a navegadores no Chrome, Firefox, Safari e Edge. Os relatórios são enviados com o tipo de conteúdoapplication/csp-report
e têm um formato específico para a CSP. Esses relatórios são chamados de "Relatórios de CSP de nível 2" e não dependem da API Reporting. - Com a API Reporting, isso é feito pelo cabeçalho
Report-To
(legado) ou peloReporting-Endpoints
mais recente (v1). Essa opção só está disponível no Chrome e no Edge. As solicitações de relatório têm o mesmo formato que outras solicitações da API Reporting e o mesmo tipo de conteúdoapplication/reports+json
.
Usar a primeira abordagem (apenas report-uri
) não é mais recomendado e usar a segunda abordagem tem alguns benefícios. Em especial, ela permite que você use uma única forma de configurar relatórios para todos os tipos de relatórios, bem como definir um endpoint genérico, porque todas as solicitações de relatório geradas pela API Reporting⏤CSP e outras ⏤ têm o mesmo formato application/reports+json
.
No entanto, apenas alguns navegadores são compatíveis com report-to
.
Portanto, é recomendável manter o report-uri
junto com a abordagem da API Reporting (Report-To
ou melhor, Reporting-Endpoints
) para receber relatórios de violação da CSP em vários navegadores. Em um navegador que reconhece report-uri
e report-to
, report-uri
será ignorado se report-to
estiver presente. Em um navegador que reconhece apenas report-uri
, somente report-uri
será considerado.
Etapa 1 (faça agora): se você ainda não adicionou, inclua
report-to
ereport-uri
. Os navegadores que aceitam apenasreport-uri
(Firefox) usamreport-uri
e que também são compatíveis comreport-to
(Chrome, Edge) usamreport-to
. Para especificar os endpoints nomeados que você usará emreport-to
, use os cabeçalhosReport-To
eReporting-Endpoints
. Isso garante que você receba relatórios de clientes mais antigos e mais recentes do Chrome e do Edge.Etapa 3 (começar mais tarde): quando todos ou a maioria dos usuários tiverem atualizado para instalações posteriores do Chrome ou do Edge (96 e mais recentes), remova
Report-To
(v0) e mantenha apenasReporting-Endpoints
. Mantenhareport-uri
para que você ainda receba relatórios sobre os navegadores compatíveis apenas com ele.
Veja exemplos de código para essas etapas em Migração de relatórios de CSP.
Migração: exemplo de código
Visão geral
Se você estiver usando a API Reporting legada (v0) para receber relatórios de violação de um COOP
(cabeçalho Cross-Origin-Opener-Policy
), um COEP (Cross-Origin-Embedder-Policy
) ou uma política de documento
(cabeçalho Document-Policy
), não será necessário mudar esses cabeçalhos de política ao migrar
para a API Reporting v1. É necessário migrar do cabeçalho Report-To
legado para o novo
cabeçalho Reporting-Endpoints
.
Se você estiver usando a API Reporting legada (v0) para receber relatórios de violação de uma CSP
(cabeçalho Content-Security-Policy
), talvez seja necessário ajustar o Content-Security-Policy
como parte da
migração para a nova API Reporting (v1).
Migração básica
Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default" Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/default" }] }
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Com a v1, ainda é possível enviar tipos de relatórios específicos para endpoints específicos. Mas só é possível ter um URL por endpoint.
Como observar todas as páginas
app.get("/", (request, response) => { response.set("Report-To", …) response.render(...) }); app.get("/page1", (request, response) => { response.render(...) });
// Use a middleware to set the reporting endpoint(s) for *all* requests. app.use(function(request, response, next) { response.set("Reporting-Endpoints", …); next(); }); app.get("/", (request, response) => { response.render(...) }); app.get("/page1", (request, response) => { response.render(...) });
Migração de relatórios da CSP
Content-Security-Policy: ...; report-uri https://reports.example/main
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint Report-To: main-endpoint="https://reports.example/main"
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint Reporting-Endpoints: main-endpoint="https://reports.example/main" Report-To: ...
Leia mais
- Monitorar seu aplicativo da Web com a API Reporting (postagem principal sobre a API Reporting)
- Especificação: API Reporting legada (v0)
- Especificação: nova API Reporting (v1)
Imagem principal de Nine Koepfer / @enka80 no Unsplash (links em inglês), editada. Agradecemos muito a Ian Clelland, Eiji Kitamura e Milica Mihajlija pelas avaliações e sugestões neste artigo.