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 sobre erros que acontecem no seu site à medida que os visitantes o usam. Ele oferece visibilidade sobre intervenções, falhas, 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 todos os navegadores.

Resumo

Desenvolvedores de sites

Se você já tiver a 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).

⚠️ 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 a v0 e a 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.

• Ambas as APIs são compatíveis com os mesmos tipos de relatórios, com uma exceção: a v1 não aceita relatórios de erro de rede. Leia 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?

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 (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ê 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 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". Com a 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 (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 de registro de erros de rede, mantenha Report-To até que um novo mecanismo seja implementado para o registro de erros de rede.

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:

• Com o cabeçalho CSP sozinho pela 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 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). 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 têm o mesmo formato.application/reports+json

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 (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. Mantenha report-uri para continuar recebendo relatórios para navegadores que só oferecem suporte a ele.

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 versão 1, 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 a Ian Clelland, Eiji Kitamura e Milica Mihajlija pelas revisões e sugestões neste artigo.