Migrar para a API Reporting v1

Uma nova versão da API Reporting está disponível. Ele é mais privado e tem mais chances de ser compatível com vários navegadores.

Maud Nalpas

A API Reporting informa sobre erros que acontecem no seu site enquanto os visitantes o usam. Ele oferece visibilidade sobre intervenções e falhas do navegador, violações da Política de Segurança de Conteúdo, violações de COOP/COEP, avisos de descontinuação e muito mais.

Uma nova versão da API Reporting está disponível. A nova API é mais simples e tem mais chances de ser compatível com vários navegadores.

Resumo

Desenvolvedores de sites

Se você já tiver uma funcionalidade de relatórios para 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: exemplo de código.

Se você estiver adicionando a funcionalidade de relatórios ao seu site agora: use apenas o novo cabeçalho (Reporting-Endpoints).

⚠️ Nos dois 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ê estiver mantendo ou operando um serviço de endpoint, espere mais tráfego à medida que você ou desenvolvedores externos migrarem para a API Reporting v1 (cabeçalho Reporting-Endpoints).

Continue lendo para conferir detalhes e exemplos de código.

Registro de erros de rede

Um novo mecanismo para o registro de erros de rede será desenvolvido. Quando isso estiver disponível, mude da API Reporting v0 para esse novo mecanismo.

Demonstração e código

• Site de demonstração: nova API de relatórios (v1)
• Código do site de demonstração

Diferenças entre 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 são compatíveis com os mesmos tipos de relatórios, com uma exceção: a v1 não é compatível com relatórios de erros de rede. Leia mais nas etapas de migração.
• A v0 não é e não será compatível com todos os navegadores. A v1 tem mais chances de ser compatível com vários navegadores no futuro.

O que não muda

• O formato e a estrutura dos relatórios não mudaram.
• A solicitação enviada pelo navegador ao endpoint continua sendo uma solicitação POST de Content-type application/reports+json.
• O mapeamento de determinados endpoints para determinados tipos de relatórios é compatível com as versões v0 e v1.
• A função do endpoint default não mudou.

• A API Reporting v1 não tem impacto no ReportingObserver. O ReportingObserver continua tendo acesso a todos os relatórios observáveis, e o formato deles é idêntico.

Todas as diferenças entre v0 e v1

Desenvolvedores de endpoints: esperem mais tráfego

Se você configurou seu próprio servidor como um endpoint de geração de relatórios ou se está desenvolvendo ou mantendo um coletor de relatórios como um serviço, espere mais tráfego para esse endpoint.

Isso acontece porque os relatórios não são agrupados em lotes com a API Reporting v1 como são com a API Reporting v0. Portanto, à medida que os desenvolvedores de aplicativos começarem a migrar para a API Reporting v1, o número de relatórios vai permanecer semelhante, mas o volume de solicitações para o servidor de endpoint vai aumentar.

Desenvolvedores de aplicativos: migre para Reporting-Endpoints (v1)

O que você deve fazer?

Usar a nova API Reporting (v1) tem vários benefícios ✅:

• Os indicadores do navegador são positivos, o que significa que é possível esperar suporte entre navegadores para a v1 (ao contrário da v0, que só é compatível com o Chrome e o Edge).
• A API é mais simples.
• Estamos desenvolvendo ferramentas para a nova API Reporting (v1).

Com isso em mente:

• 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 a funcionalidade de relatórios para violações da Política de Segurança de Conteúdo, confira as etapas específicas de migração para relatórios da CSP.
• Se o site ainda não usa a API Reporting e você está adicionando a funcionalidade de geração de relatórios agora, 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 o Network Error Logging será desenvolvido. Até que ele esteja disponível, use a API Reporting v0. Se você precisar do Network Error Logging junto com outros tipos de relatórios, use ambos Report-To (v0) e Reporting-Endpoints (v1). A v0 oferece o Network Error Logging, e a v1 oferece relatórios de todos os outros tipos.

Etapas da migração

O objetivo desta migração é não perder os relatórios que você recebia 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 que oferecem suporte a Reporting-Endpoints vão usar Reporting-Endpoints, e as que não oferecem vão usar Report-To. O formato da solicitação e do relatório é o mesmo para v0 e 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.

   Com a v0, era possível definir endpoints de relatórios apenas em algumas respostas, e outros documentos (páginas) nessa origem usariam esse endpoint "ambiente". Com a v1, devido à diferença no escopo, é necessário definir o cabeçalho Reporting-Endpoints em todas as respostas que possam gerar relatórios.

3. Etapa 3 (começar depois): quando todos ou a maioria dos usuários tiverem atualizado para instalações mais recentes do Chrome ou do Edge (96 e versões mais recentes), remova Report-To (v0) e mantenha apenas Reporting-Endpoints.

   Uma exceção: se você precisar de relatórios de Network Error Logging, mantenha Report-To até que um novo mecanismo seja implementado para o Network Error Logging.

Confira exemplos de código no livro de receitas de migração.

Etapas de migração para relatórios de CSP

Há duas maneiras de configurar relatórios de violação da Content-Security-Policy:

• Com o cabeçalho CSP sozinho usando a diretiva report-uri. Ele tem suporte para vários navegadores, como 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 CSP. Esses relatórios são chamados de "Relatórios do CSP nível 2" e não dependem da API Reporting.
• Com a API Reporting, isso é feito pelo cabeçalho Report-To (legado) ou pelo mais recente Reporting-Endpoints (v1). Esse recurso só está disponível no Chrome e no Edge. As solicitações de relatórios 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 tem alguns benefícios. Em particular, ela permite usar uma única maneira de configurar relatórios de todos os tipos, além de definir um endpoint genérico, já que 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. Por isso, recomendamos que você mantenha report-uri junto com a abordagem da API Reporting (Report-To ou melhor, Reporting-Endpoints) para receber relatórios de violação da CSP de 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, adicione report-to junto com report-uri. Navegadores que oferecem suporte apenas a report-uri (Firefox) vão usar report-uri, e navegadores que também oferecem suporte a report-to(Chrome, Edge) vão usar report-to. Para especificar os endpoints nomeados que você vai 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 depois): quando todos ou a maioria dos usuários tiverem atualizado para instalações mais recentes do Chrome ou do Edge (96 e versões mais recentes), remova Report-To (v0) e mantenha apenas Reporting-Endpoints. Mantenha report-uri para continuar recebendo relatórios de navegadores que só são compatíveis com ele.

Confira exemplos de código para essas etapas em Migração de relatórios da 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 uma COOP (cabeçalho Cross-Origin-Opener-Policy), uma COEP (Cross-Origin-Embedder-Policy) ou uma política de documentos (cabeçalho Document-Policy), não é necessário mudar esses cabeçalhos de política ao migrar para a API Reporting v1. O que você precisa fazer é 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 seu 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 específicos de relatórios para endpoints específicos. Mas você só pode ter um URL por endpoint.

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

Leitura adicional

• Monitore 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)

Agradecemos muito a Ian Clelland, Eiji Kitamura e Milica Mihajlija pelas revisões e sugestões neste artigo.