Migrar para a API Reporting v1

Uma nova versão da API Reporting está disponível. É mais privado e mais provável de ser suportado em todos os navegadores.

Maud Nalpas

Atenção:esta postagem explica como migrar para a nova versão da página de relatórios API (v1). Se você ainda não conhece a API Reporting ou precisa de exemplos detalhados de uso, acesse a página publicar na API Reporting.

A API Reporting informa erros que ocorrem em todo o seu site à medida que os visitantes o utilizam. Dá visibilidade das intervenções e falhas do navegador, violações da Política de Segurança de Conteúdo Violações da COOP/COEP, avisos de descontinuação e muito mais.

Uma nova versão da API Reporting está disponível. A nova API é mais enxuta e tem maior probabilidade de ser compatíveis com todos os navegadores.

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

Resumo

Desenvolvedores de sites

Se você já tiver a funcionalidade de geração de relatórios no 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 site agora há pouco: use apenas o cabeçalho novo. (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ê mantém um serviço de endpoint ou opera por conta própria, espere mais tráfego ou desenvolvedores externos migram para a API Reporting v1 (cabeçalho Reporting-Endpoints).

Continue lendo para conferir mais detalhes e exemplos de código.

Registro de erros de rede

Cuidado: se você usar a geração de registros 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 Reporting (v1)
• Código para o site de demonstração

Diferenças entre v0 e v1

O que muda?

• A superfície da API é diferente.

v0 (legada)

 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 nomes endpoints. 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) sobre isso usa esses endpoints de ambiente automaticamente.

v1 (novo)

Na v1, é necessário definir o cabeçalho Reporting-Endpoints em todas as respostas que podem gerar e detecção de ameaças.

• As duas APIs são compatíveis com os mesmos tipos de relatório, com uma exceção: a v1 não oferece suporte aos relatórios de erros de rede. Leia mais nas etapas de migração.
• A v0 não é e não será compatível com todos os navegadores. é mais provável que v1 seja compatível com em vários navegadores no futuro.

O que permanece inalterado

• O formato e a estrutura dos relatórios não foram alterados.
• A solicitação enviada pelo navegador ao endpoint permanece uma solicitação POST de Content-type application/reports+json
• O mapeamento de determinados endpoints para determinados tipos de relatório é suportado nas versões v0 e v1.
• A função do endpoint default não foi alterada.

• A API Reporting v1 não afeta o ReportingObserver. ReportingObserver continua tendo acesso a todos os relatórios observáveis, e o formato é idênticos.

Todas as diferenças entre v0 e v1

	API Reporting legada (v0) Cabeçalho Report-To	Nova API Reporting (v1) Cabeçalho Reporting-Endpoints
Suporte ao navegador	Chrome 69 ou mais recente e Edge 69 ou mais recente.	Chrome 96 ou mais recente e Edge 96 ou mais recente. O Firefox oferece suporte. O Safari não faz objeções. Consulte os indicadores do navegador.
Endpoints	Envia relatórios para qualquer um dos 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órios que podem ser gerados por esta API	Suspensão de uso Intervenção Acidente COOPA/COEP Nível 3 da Política de Segurança de Conteúdo (CSP - nível 3) Registro de erros de rede (NEL) . Saiba mais sobre os tipos de relatório 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 (agrupamento em lotes)	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 à privacidade. Relatórios do mesmo documento (página) podem ser enviados juntos.
Suporte para balanceamento de carga / prioridades	Sim	Não

Desenvolvedores de endpoint: esperam mais tráfego

Se você configurou seu próprio servidor como um endpoint de relatórios ou se estiver desenvolvendo ou mantendo um Coletor como serviço de relatórios, é esperado mais tráfego para esse endpoint.

Isso ocorre porque os relatórios não são agrupados com a API Reporting v1 do que com a API Reporting v0. Portanto, à medida que os desenvolvedores de aplicativos começarem a migrar para a API Reporting v1, o número de relatórios será permanecem semelhantes, mas o volume de solicitações para o servidor de endpoint aumenta.

Desenvolvedores de aplicativos: migrar para o Reporting-Endpoints (v1)

O que você deve fazer?

Usar a nova API Reporting (v1) traz vários benefícios ✅:

• Os sinais do navegador são positivos, ou seja, que o suporte entre navegadores pode ser esperado para a v1 (ao contrário da v0, que só é suportada no Chrome e Edge).
• A API é mais enxuta.
• As ferramentas estão sendo desenvolvidas em torno da nova API Reporting (v1).

Pensando nisso:

• Caso seu site já use a API Reporting v0 com o cabeçalho Report-To, migre para o API Reporting v1 (consulte as etapas de migração). Se seu site já usa funcionalidade de relatórios para violações da Política de Segurança de Conteúdo, verifique as etapas de migração específicas para a geração de relatórios da CSP.
• Se seu site ainda não usa a API Reporting e você está adicionando a funcionalidade de relatórios: usar a nova API Reporting (v1) (o cabeçalho Reporting-Endpoints). Há uma exceção isto: se você precisar usar o registro de erros de rede, use Report-To (v0). 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 desenvolvida⏤ até que 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 ambos Report-To (v0) e Reporting-Endpoints (v1). v0 fornece Geração de registros de erros de rede, e a v1 fornece relatórios de todos os outros tipos.

Etapas da migração

Sua meta nessa migração é não perder os relatórios conseguidos com a v0.

Observação:como apenas o Chrome e o Edge são compatíveis com a API Reporting v0, você não precisa se concentrar outros navegadores durante a migração para a v1. No entanto, o suporte mais amplo a navegadores pode virá. Não há bugs de rastreamento para esses navegadores no momento, 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 Edge graças ao Report-To (v0).

   As instâncias do navegador compatíveis com Reporting-Endpoints usarão Reporting-Endpoints. instâncias que não vão fazer a substituição por Report-To. O formato de solicitação e de relatório é o mesmo para v0 e v1.

2. Etapa 2 (faça agora): o cabeçalho Reporting-Endpoints precisa estar definido em todas as respostas pode gerar relatórios.

   Na v0, é possível definir endpoints de relatórios somente em algumas respostas e em outros documentos. (páginas) dessa origem usariam esse "ambiente" endpoint do Google Cloud. Na v1, por causa da diferença entre escopo, é necessário definir o cabeçalho Reporting-Endpoints em todas as respostas que podem gerar e detecção de ameaças.

3. Etapa 3 (começar mais tarde): depois que todos ou a maioria dos usuários tiverem atualizado para o Chrome ou o Edge mais recente instalações (96 e mais recentes), remova Report-To (v0) e mantenha apenas Reporting-Endpoints.

   Uma exceção: se você precisa de relatórios do registro de erros de rede, mantenha Report-To até que um novo está em vigor para o registro de erros de rede.

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

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

A Content-Security-Policy pode ser usada de duas formas relatórios de violação podem ser configurados:

• Apenas com o cabeçalho da CSP usando a diretiva report-uri. Ele oferece um amplo suporte a navegadores, 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 do CSP. Esses relatórios são chamados de "Relatórios de nível 2 da CSP" e fazer não dependem da API Reporting.
• Com a API Reporting, isso é feito pelo cabeçalho Report-To (legado) ou pela versão mais recente Reporting-Endpoints (v1). Isso só é compatível com o Chrome e o Edge. As solicitações de relatório têm 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 tem alguns benefícios. Em particular, ele permite que você use uma única maneira de configurar relatórios para todos os tipos, além de 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 são compatíveis com report-to. Portanto, é recomendável manter report-uri com a abordagem da API Reporting (Report-To ou melhor, Reporting-Endpoints) para receber denúncias de violação da CSP de vários navegadores. Em um navegador que reconheça report-uri e report-to, report-uri será ignorado se report-to está 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 ao lado de report-uri. Navegadores compatíveis apenas com o report-uri (Firefox) usarão report-uri e navegadores que também suporte report-to(Chrome, Edge) usará report-to. Para especificar os endpoints nomeados, você vai usar em report-to, use os cabeçalhos Report-To e Reporting-Endpoints. Isso garante que você receba de clientes Chrome e Edge de clientes mais antigos e novos.

2. Etapa 3 (começar mais tarde): depois que todos ou a maioria dos usuários tiverem atualizado para o Chrome ou o Edge mais recente instalações (96 e mais recentes), remova Report-To (v0) e mantenha apenas Reporting-Endpoints. Manter report-uri, então você ainda vai receber relatórios sobre os navegadores compatíveis apenas com esse recurso.

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

Migração: exemplo de código

Visão geral

Se você estiver usando a API Reporting (v0) legada para receber relatórios de violação de uma COOP (cabeçalho Cross-Origin-Opener-Policy), um COEP (Cross-Origin-Embedder-Policy) ou uma política de documentos (cabeçalho Document-Policy): não é necessário mudar esses cabeçalhos de política durante a migração. à 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 (v0) legada para receber relatórios de violação de uma CSP (cabeçalho Content-Security-Policy), pode ser necessário ajustar seu Content-Security-Policy como parte migração para a nova API Reporting (v1).

Migração básica

Código legado (com 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 v0 junto com 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 geração de relatórios no seu site, mantenha o Report-To apenas temporariamente (até que a maioria dos clientes Chrome e Edge tenham sido atualizados) para evitar a perda de relatórios.

Se você precisar dos registros de erros de rede, mantenha Report-To até a substituição deles for disponibilizado.

Novo código (somente com a v1)

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

Seu código terá esta aparência no futuro, quando a maioria dos clientes Chrome e Edge for atualizada e oferecerem suporte à API v1.

Com a v1, ainda é possível enviar tipos de relatórios específicos para endpoints específicos. Mas você pode ter apenas um URL por endpoint.

Observar todas as páginas

Código legado (com 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. Outra opção documentos (páginas) nessa origem usam automaticamente esses endpoints de ambiente. Aqui, os endpoints definidos de "/" são usados para todas as respostas, por exemplo, para page1.

Novo código (com v1), por exemplo, com 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(...)
});

Na v1, é preciso definir o cabeçalho Reporting-Endpoints em todas de dados que podem gerar relatórios.

Migração de relatórios da CSP

Código legado, apenas com report-uri

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

Usar apenas o report-uri não é mais recomendado. Caso seu código seja semelhante ao mostrado acima, migre. Consulte os exemplos de Novo código abaixo (em verde).

Um código legado melhor, com report-uri e a diretiva report-to com as Cabeçalho de relatório para (v0)

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

É melhor: esse código usa o report-to, a substituição mais recente para report-uri. Ele ainda mantém o report-uri para compatibilidade com versões anteriores. várias não são compatíveis com navegadores report-to mas não oferecem suporte report-uri

Ainda assim, poderia ser melhor: esses códigos usam a API Reporting v0 (cabeçalho Report-To). Migre para a v1: consulte as "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é a diretiva report-to é compatível com todos os navegadores. Consulte a compatibilidade do navegador tabela.

Manter Report-To ao lado de Reporting-Endpoints temporariamente. Assim que a maior parte dos recursos do Chrome e do Edge os visitantes fizeram 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)

Imagem principal de Nine Koepfer / @enka80 no Unsplash, editada. Muito obrigado ao Ian Clelland, Eiji Kitamura e Milica Mihajlija por suas avaliações e sugestões sobre o assunto artigo.