Migrar para a API Reporting v1

Uma nova versão da API Reporting está disponível. Ela é mais privada 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 quando os visitantes o usam. Ela 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 suspensão de uso e muito mais.

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

Resumo

Desenvolvedores de sites

Se você já tem 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 um serviço de endpoint ou operando o seu próprio, 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 ele estiver disponível, mude da API Reporting v0 para esse 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 a v0 e a v1

O que muda?

• A superfície 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 oferecem suporte aos mesmos tipos de relatório, com uma exceção: a v1 não oferece suporte a relatórios de erros de rede. Leia mais nas etapas de migração.
• A v0 não é e não será compatível com vários navegadores. A v1 tem mais chances de ser compatível com vários navegadores no futuro.

O que permanece inalterado

• 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ório é compatível com as versões v0 e v1.
• O papel 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 a v0 e a v1

Desenvolvedores de endpoints: espere mais tráfego

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

Isso ocorre porque os relatórios não são agrupados com a API Reporting v1 como são com a API Reporting v0. Portanto, à medida que os desenvolvedores de aplicativos começam 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?

O uso da nova API Reporting (v1) tem vários benefícios ✅:

• Os indicadores do navegador são positivos, o que significa que o suporte entre navegadores pode ser esperado 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 na nova API Reporting (v1).

Com isso em mente:

• Se o site já usa a API Reporting v0 com o Report-To cabeçalho, 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 de migração específicas para relatórios de CSP.
• Se o site ainda não usa a API Reporting e você está adicionando a funcionalidade 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 registro de erros de rede, use Report-To (v0). O registro de erros de rede não é compatível com a API Reporting v1. Um novo mecanismo para o registro de erros de rede será desenvolvido. Até que ele esteja disponível, use a API Reporting v0. Se você precisar do registro de erros de rede junto com outros tipos de relatório, use tanto Report-To (v0) quanto Reporting-Endpoints (v1). A v0 oferece o registro de erros de rede e a v1 oferece relatórios de todos os outros tipos.

Etapas da migração

Seu objetivo nessa migração é não perder os relatórios que você costumava receber com a v0.

1. Etapa 1 (fazer agora): use os dois cabeçalhos: Report-To (v0) e Reporting-Endpoints (v1).

   Com isso, você terá:

   • 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 do navegador que oferecem suporte a Reporting-Endpoints vão usar Reporting-Endpoints, e as instâncias que não oferecem suporte vão usar Report-To. O formato de solicitação e relatório é o mesmo para a v0 e a v1.

2. Etapa 2 (fazer agora) : verifique se o cabeçalho Reporting-Endpoints está definido em todas as respostas que possam 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 "ambiental". 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 mais tarde) : depois que 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 registro de erros de rede, mantenha Report-To até que um novo mecanismo seja implementado para o registro de erros de rede.

Consulte exemplos de código no manual de migração.

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

Há duas maneiras de configurar relatórios de violação da Política de Segurança de Conteúdo:

• Apenas com o cabeçalho CSP usando a diretiva report-uri. Isso tem amplo suporte ao navegador, 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 CSP. Esses relatórios são chamados de "Relatórios de CSP Nível 2" e não dependem da API Reporting.
• Com a API Reporting, ou seja, pelo cabeçalho Report-To (legado) ou o mais recente Reporting-Endpoints (v1). Isso é compatível apenas com o Chrome e o 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.

O uso da primeira abordagem (apenas report-uri) não é mais recomendado e o uso da segunda abordagem tem alguns benefícios. Em particular, ele permite usar uma única maneira de configurar relatórios para todos os tipos de relatório, 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 oferecem suporte a report-to. Portanto, é recomendável manter report-uri junto com a abordagem da API Reporting (Report-To ou melhor, Reporting-Endpoints) para receber relatórios de violação de 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, apenas report-uri será considerado.

1. Etapa 1 (fazer agora): se você ainda não adicionou, adicione report-to junto com report-uri. Os navegadores que oferecem suporte apenas a report-uri (Firefox) vão usar report-uri, e os 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 mais tarde) : depois que 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ó oferecem suporte a ele.

Consulte exemplos de código para essas etapas na 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. 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 um CSP (cabeçalho Content-Security-Policy), talvez seja necessário ajustar a 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ório específicos para endpoints específicos. No entanto, só é possível 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 de 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 (post principal sobre a API Reporting)
• Especificação: API Reporting legada (v0)
• Especificação: nova API Reporting (v1)

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