Migrar para a API Reporting v1

Uma nova versão da API Reporting está disponível. Essa é uma interface mais privada e compatível com vários navegadores.

Maud Nalpas

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.

• 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 de Content-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. O ReportingObserver 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

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, use Report-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 dois Report-To (v0) e Reporting-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.

1. Etapa 1 (faça agora): use os dois cabeçalhos Report-To (v0) e Reporting-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ão Reporting-Endpoints e as instâncias que não forem compatíveis serão substituídas por Report-To. O formato da solicitação e do relatório é o mesmo para a v0 e a v1.

2. 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.

3. 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 apenas Reporting-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údo application/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 pelo Reporting-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údo application/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.

1. Etapa 1 (faça agora): se você ainda não adicionou, inclua report-to e report-uri. Os navegadores que aceitam apenas report-uri (Firefox) usam report-uri e que também são compatíveis com report-to(Chrome, Edge) usam report-to. Para especificar os endpoints nomeados que você usará em report-to, use os cabeçalhos Report-To e Reporting-Endpoints. Isso garante que você receba relatórios de clientes mais antigos e mais recentes do Chrome e do Edge.

2. 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 apenas Reporting-Endpoints. Mantenha report-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.