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

Atenção: esta postagem aborda como migrar para a nova versão da API Reporting (v1). Se você ainda não conhece a API Reporting ou precisa de exemplos detalhados de uso, consulte a postagem principal na API Reporting.

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.

Observação: a API Reporting legada é chamada de API Reporting v0. A nova API Reporting é chamada de API Reporting v1.

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

Atenção: se você usa o Registro de erros de rede, continue usando Report-To (v0), porque 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. 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.

v0 (legado)

 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

{0 usa o cabeçalho Report-To para configurar grupos de endpoints nomeados, e a diretiva report-to em outros cabeçalhos para se referir a esses grupos de endpoints.

v1 (novo)

 Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
 Document-Policy: ...; report-to main-endpoint

A v1 usa o cabeçalho Reporting-Endpoints para configurar endpoints nomeados. Assim como na v0, ela usa a diretiva report-to em outros cabeçalhos para se referir a esses grupos de endpoints.

• O escopo do relatório é diferente.

v0 (legada)

Com a v0, é possível definir endpoints de relatórios apenas em algumas respostas. Outros documentos (páginas) nessa origem usariam automaticamente esses endpoints ambientais.

v1 (novo)

Com a v1, é necessário definir o cabeçalho Reporting-Endpoints em todas as respostas que podem gerar relatórios.

• 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

	API Reporting legada (v0) Report-To cabeçalho	Nova API Reporting (v1) Reporting-Endpoints cabeçalho
Suporte ao navegador	Chrome 69 e mais recentes e Edge 69 e mais recentes.	Chrome 96+ e Edge 96+. O Firefox oferece suporte. O Safari não se opõe. Consulte sinais do navegador.
Endpoints	Envia relatórios para vários coletores de relatórios (vários URLs definidos por grupo de endpoints).	Envia relatórios para coletores específicos (somente um URL definido por endpoint).
Superfície da API	Usa o cabeçalho `Report-To` para configurar grupos de endpoints nomeados.	Usa o cabeçalho `Reporting-Endpoints` para configurar endpoints nomeados.
Tipos de relatório que podem ser gerados por essa API	Suspensão de uso Intervenção Acidente COOP/COEP Content-Security-Policy Level 3 (CSP Level 3) Registro de erros de rede (NEL) Saiba mais sobre os tipos de denúncia na postagem da API Reporting.	Inalterado, exceto da Geração de registros de erros de rede (NEL): isso não é compatível com a nova API Reporting (v1).
Escopo do relatório	Origem. O cabeçalho Report-To de um documento afeta outros documentos (páginas) dessa origem. O campo url de um relatório ainda varia de acordo com o documento.	Document. O cabeçalho Reporting-Endpoints de um documento afeta apenas esse documento. O campo url de um relatório ainda varia de acordo com o documento.
Isolamento de relatórios (batch)	Documentos (páginas) ou sites/origens que geram um relatório aproximadamente ao mesmo tempo e que têm o mesmo endpoint de relatórios serão agrupados: eles serão enviados na mesma mensagem para o endpoint de relatórios.	Relatórios de documentos (páginas) diferentes nunca são enviados juntos. Mesmo que dois documentos (páginas) da mesma origem gerem um relatório ao mesmo tempo para o mesmo endpoint, eles não serão agrupados. Esse é um mecanismo para mitigar ataques de privacidade. Os relatórios do mesmo documento (página) podem ser enviados juntos.
Suporte para balanceamento de carga / prioridades	Sim	Não

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.

Observação: como apenas o Chrome e o Edge oferecem suporte à API Reporting v0, não é necessário se concentrar em outros navegadores durante a migração para a v1. No entanto, é possível que o suporte a navegadores mais amplos esteja chegando. No momento, não há bugs de rastreamento para esses navegadores, mas isso pode mudar.

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

Código legado (com a v0)

Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }

Novo código (código de transição com a v0 e a v1)

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" }] }

Se você já tem a funcionalidade de relatórios no seu site, mantenha Report-To apenas temporariamente, até que a maioria dos clientes do Chrome e do Edge sejam atualizados, para evitar a perda de relatórios.

Se você precisar do registro de erros de rede, mantenha Report-To até que a substituição desse registro esteja disponível.

Novo código (somente com a v1)

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

Esta é a aparência do código no futuro, quando a maioria dos clientes do Chrome e do Edge for atualizada e oferecer suporte à API v1.

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

Código legado (com a v0), por exemplo, com o Express

app.get("/", (request, response) => {
  response.set("Report-To", …)
  response.render(...)
});
app.get("/page1", (request, response) => {
  response.render(...)
});

Com a v0, é possível definir endpoints de relatórios apenas em algumas respostas. Outros documentos (páginas) nessa origem usam automaticamente esses endpoints de ambiente. Aqui, os endpoints definidos para "/" são usados para todas as respostas, por exemplo, para page1.

Novo código (com a v1), por exemplo, com o Express

// 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(...)
});

Com a v1, é necessário definir o cabeçalho Reporting-Endpoints em todas as respostas que podem gerar relatórios.

Migração de relatórios de CSP

Código legado, apenas com report-uri

Content-Security-Policy: ...; report-uri https://reports.example/main

O uso exclusivo de report-uri não é mais recomendado. Se o código for semelhante ao acima, migre. Confira os novos exemplos de código abaixo (em verde).

Melhor código legado, com report-uri e a diretiva report-to com o cabeçalho Report-To (v0)

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Report-To: main-endpoint="https://reports.example/main"

Melhor: este código usa "report-to", a substituição mais recente de "report-uri". Ele ainda mantém o URI do relatório disponível para compatibilidade com versões anteriores. Vários navegadores não oferecem suporte a report-to, mas são compatíveis com report-uri.

Ainda assim, isso pode ser melhorado: esses códigos usam a API Reporting v0 (cabeçalho Report-To). Migrar para a v1: confira os exemplos de "Novo código" abaixo (em verde).

Novo código, com report-uri e a diretiva report-to com o cabeçalho Reporting-Endpoints (v1)

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Reporting-Endpoints: main-endpoint="https://reports.example/main"
Report-To: ...

Mantenha a diretiva report-uri junto com a diretiva report-to até que a diretiva report-to seja compatível com todos os navegadores. Consulte a tabela de compatibilidade com navegadores.

Mantenha Report-To ao lado de Reporting-Endpoints temporariamente. Depois que a maioria dos visitantes do Chrome e do Edge fizer upgrade para mais de 96 versões do navegador, remova o 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.