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
Maud Nalpas
X GitHub

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

Diferenças entre a v0 e a v1

O que muda?

  • A plataforma 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 fazer referência 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 a v0, ela usa a diretiva report-to em outros cabeçalhos para fazer referência a esses grupos de endpoints.

  • O escopo do relatório é diferente.
v0 (legado)

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

API Reporting legada (v0)
Report-To cabeçalho		 Nova API Reporting (v1)
Reporting-Endpoints cabeçalho
Suporte ao navegador Chrome 69 e versões mais recentes e Edge 69 e versões 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 (apenas 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. 		Não houve mudanças, exceto para o Registro de erros de rede (NEL): não há suporte para isso na 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 diferentes que geram um relatório no mesmo horário e têm o mesmo endpoint de relatório são agrupados: eles são enviados na mesma mensagem para o endpoint de relatório.
  • 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?

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

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 o Report-To até que a substituição do registro de erros de rede 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 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

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 esses endpoints automaticamente. 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, com apenas 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 report-uri para compatibilidade com versões anteriores. Vários navegadores não oferecem suporte a report-to, mas oferecem suporte a 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 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. Quando a maioria dos visitantes do Chrome e do Edge tiverem feito upgrade para a versão 96 ou mais recente do navegador, remova Report-To.

Leitura adicional

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