Migrar para a API Reporting v1

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

Maud Nalpas

A API Reporting informa erros que ocorrem em todo o seu site à medida que os visitantes o utilizam. Ele oferece visibilidade sobre intervenções, falhas, violações de políticas 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 todos os navegadores.

Resumo

Desenvolvedores de sites

Se você já tiver a funcionalidade de relatórios do 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).

⚠️ Em ambos os casos, defina o cabeçalho Reporting-Endpoints em todas as respostas que podem 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 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 de relatórios (v1)
• Código do site de demonstração

Diferenças entre v0 e 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.

• Ambas as 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 erro de rede. Saiba mais nas etapas de migração.
• A v0 não tem e não terá suporte em todos os navegadores. A v1 tem mais chances de ter suporte em vários navegadores no futuro.

O que permanece inalterado

• O formato e a estrutura dos relatórios não mudam.
• 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 a v0 e a v1.
• A função do endpoint default não muda.

• 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 endpoint: espere mais tráfego

Se você configurou seu próprio servidor como um endpoint 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 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 migram 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 o Reporting-Endpoints (v1)

O que você deve fazer?

Usar a nova API Reporting (v1) traz 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 (diferente da v0, que tem suporte apenas no Chrome e no Edge).
• A API é mais simples.
• As ferramentas estão sendo desenvolvidas em torno da 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 envio de relatórios para violações da Política de Segurança de Conteúdo, confira as etapas específicas de migração para o envio de relatórios da CSP.
• Se o site ainda não usa a API Reporting e você está adicionando a funcionalidade de relatórios: use a nova API Reporting (v1) (cabeçalho Reporting-Endpoints). Há uma exceção a isso: se você precisar usar o registro de erros de rede, use Report-To (v0). No momento, o registro de erros de rede não é compatível com a API Reporting v1. Um novo mecanismo para registro de erros de rede será desenvolvido.⏤Até que ele esteja disponível, use a API Reporting v0. Se você precisar de registro de erros de rede com outros tipos de relatórios, use ambos Report-To (v0) e Reporting-Endpoints (v1). O v0 oferece registro de erros de rede, e o v1 oferece relatórios de todos os outros tipos.

Etapas da migração

O objetivo dessa 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ê obtém:

   • 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 que não oferecem vão usar Report-To. O formato de solicitação e relatório é o mesmo para v0 e v1.

2. Etapa 2 (agora): verifique se o cabeçalho Reporting-Endpoints está definido em todas as respostas que podem gerar relatórios.

   Com a v0, você pode definir endpoints de relatórios apenas em algumas respostas, e outros documentos (páginas) nessa origem usariam esse endpoint "ambiente". Na 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 (início posterior): depois que todos ou a maioria dos usuários tiverem atualizado para instalações mais recentes 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 do registro de erros de rede, mantenha Report-To até que um novo mecanismo esteja em vigor.

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

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

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

• Apenas com o cabeçalho da CSP usando a diretiva report-uri. Ele tem suporte a 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 o CSP. Esses relatórios são chamados de "Relatórios do nível 2 do CSP" 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). Esse recurso é 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.

A primeira abordagem (apenas report-uri) não é mais recomendada, e a segunda tem alguns benefícios. Em particular, ele permite que você use uma única maneira de configurar relatórios para todos os tipos de relatório e definir um endpoint genérico, porque todas as solicitações de relatório geradas pela API Reporting⏤CSP e outras application/reports+jsontêm o mesmo formato.

No entanto, apenas alguns navegadores oferecem suporte a report-to. Portanto, é recomendável manter report-uri 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 (agora): se você ainda não adicionou, adicione report-to com report-uri. Os navegadores que oferecem suporte apenas a report-uri (Firefox) vão usar report-uri, e os 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 posteriores do Chrome ou do Edge (96 ou mais), remova Report-To (v0) e mantenha apenas Reporting-Endpoints. Mantenha report-uri para continuar recebendo relatórios apenas dos navegadores compatíveis.

Confira exemplos de código para essas etapas em Migração de relatórios do CSP.

Migração: exemplo de código

Visão geral

Se você estiver usando a API Reporting herdada (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 documento (cabeçalho Document-Policy): não é necessário mudar esses cabeçalhos de política durante a migração para a API Reporting v1. Você precisa 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 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. No entanto, 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 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

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

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