Reporting API v1로 이전

새로운 버전의 Reporting API를 사용할 수 있습니다. 더 비공개적이고 브라우저 간에 지원될 가능성이 높습니다.

Maud Nalpas

Reporting API는 방문자가 사이트를 사용할 때 사이트 전반에서 발생하는 오류를 알려줍니다. 브라우저 개입, 브라우저 비정상 종료, 콘텐츠 보안 정책 위반, COOP/COEP 위반, 지원 중단 경고 등을 파악할 수 있습니다.

새로운 버전의 Reporting API를 사용할 수 있습니다. 새로운 API는 더 간결하고 브라우저 간에 지원될 가능성이 높습니다.

요약

사이트 개발자

사이트에 이미 보고 기능이 있는 경우: 새 헤더 (Reporting-Endpoints)를 사용하여 v1로 이전하되 기존 헤더 (Report-To)는 한동안 유지합니다. 이전: 코드 예시를 참고하세요.

사이트에 보고 기능을 지금 추가하는 경우: 새 헤더 (Reporting-Endpoints)만 사용합니다.

⚠️ 두 경우 모두 보고서를 생성할 수 있는 모든 응답에 Reporting-Endpoints 헤더를 설정해야 합니다.

보고 서비스 개발자

엔드포인트 서비스를 유지관리하거나 자체 엔드포인트 서비스를 운영하는 경우 또는 외부 개발자가 Reporting API v1 (Reporting-Endpoints 헤더)로 이전하면 트래픽이 증가 할 것으로 예상됩니다.

자세한 내용과 코드 예시를 계속 읽어보세요.

네트워크 오류 로깅

주의: 네트워크 오류 로깅을 사용하는 경우 Reporting API v1에서 네트워크 오류 로깅이 지원되지 않으므로 Report-To (v0)을 계속 사용하세요.

네트워크 오류 로깅을 위한 새로운 메커니즘이 개발될 예정입니다. 이 메커니즘이 제공되면 Reporting API v0에서 새로운 메커니즘으로 전환하세요.

데모 및 코드

v0과 v1의 차이점

변경사항

API 노출 영역이 다릅니다.

v0 (기존)

 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은 Report-To 헤더를 사용하여 명명된 엔드포인트 그룹을 구성하고 다른 헤더의 report-to 지시어를 사용하여 이러한 엔드포인트 그룹을 참조합니다.

v1 (신규)

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

v1은 Reporting-Endpoints 헤더를 사용하여 명명된 엔드포인트 를 구성합니다. v0과 마찬가지로 다른 헤더의 report-to 지시어를 사용하여 이러한 엔드포인트 그룹을 참조합니다.

보고서 범위가 다릅니다.

v0 (기존)

v0을 사용하면 일부 응답에만 보고 엔드포인트를 설정할 수 있습니다. 이 출처의 다른 문서 (페이지)는 이러한 주변 엔드포인트를 자동으로 사용합니다.

v1 (신규)

v1을 사용하면 보고서를 생성할 수 있는 모든 응답에 Reporting-Endpoints 헤더를 설정해야 합니다.

두 API는 동일한 보고서 유형을 지원하지만 한 가지 예외가 있습니다. v1은 네트워크 오류 보고서 를 지원하지 않습니다. 이전 단계에서 자세히 알아보세요.
v0은 브라우저 간에 지원되지 않으며 앞으로도 지원되지 않습니다. v1은 향후 여러 브라우저에서 지원될 가능성이 높습니다.

변경되지 않는 항목

보고서의 형식과 구조는 변경되지 않습니다.
브라우저에서 엔드포인트로 전송되는 요청은 Content-type application/reports+json의 POST 요청으로 유지됩니다.
특정 엔드포인트를 특정 보고서 유형에 매핑하는 것은 v0과 v1 모두에서 지원됩니다.
default 엔드포인트의 역할은 변경되지 않습니다.
Reporting API v1은 ReportingObserver에 영향을 미치지 않습니다. ReportingObserver 는 계속해서 관찰 가능한 모든 보고서에 액세스할 수 있으며 형식은 동일합니다.

v0과 v1의 모든 차이점

	기존 Reporting API (v0) `Report-To` 헤더	새로운 Reporting API (v1) `Reporting-Endpoints` 헤더
브라우저 지원	Chrome 69 이상 및 Edge 69 이상.	Chrome 96 이상 및 Edge 96 이상. Firefox는 지원됩니다. Safari는 반대하지 않습니다. 브라우저 신호를 참고하세요.
엔드포인트	여러 보고서 수집기 (엔드포인트 그룹당 여러 URL 정의)에 보고서를 전송합니다.	특정 보고서 수집기 (엔드포인트당 하나의 URL만 정의)에 보고서를 전송합니다.
API 노출 영역	`Report-To` 헤더를 사용하여 명명된 엔드포인트 그룹을 구성합니다.	`Reporting-Endpoints` 헤더를 사용하여 명명된 엔드포인트를 구성합니다.
이 API를 통해 생성할 수 있는 보고서 유형	지원 중단 개입 비정상 종료 COOP/COEP 콘텐츠 보안 정책 수준 3 (CSP 수준 3) 네트워크 오류 로깅 (NEL) _{Reporting API 게시물에서 보고서 유형에 관해 자세히 알아보세요.}	네트워크 오류 로깅 (NEL): 새로운 Reporting API (v1)에서 지원되지 않음 을 제외하고 변경되지 않습니다.
보고서 범위	출처에 속한 것으로 처리하는 기술입니다. 문서의 `Report-To` 헤더는 해당 출처의 다른 문서 (페이지)에 영향을 미칩니다. 보고서의 `url` 필드는 여전히 문서마다 다릅니다.	문서입니다. 문서의 `Reporting-Endpoints` 헤더는 해당 문서에만 영향을 미칩니다. 보고서의 `url` 필드는 여전히 문서마다 다릅니다.
보고서 격리 (일괄 처리)	거의 동시에 보고서를 생성하고 동일한 보고 엔드포인트를 갖는 여러 문서 (페이지) 또는 사이트/출처는 함께 일괄 처리됩니다. 즉, 보고 엔드포인트에 동일한 메시지로 전송됩니다.	다른 문서 (페이지)의 보고서는 함께 전송되지 않습니다. 동일한 출처의 두 문서 (페이지)가 동일한 엔드포인트에 대해 동시에 보고서를 생성하더라도 일괄 처리되지 않습니다. 이는 개인 정보 보호 공격을 완화하는 메커니즘입니다. 동일한 문서 (페이지)의 보고서는 함께 전송될 수 있습니다.
부하 분산 / 우선순위 지원	예	아니요

엔드포인트 개발자: 트래픽 증가 예상

자체 서버를 보고 엔드포인트로 설정했거나 보고서 수집기를 서비스로 개발 또는 유지관리하는 경우 해당 엔드포인트로의 트래픽이 증가할 것으로 예상됩니다.

이는 Reporting API v1에서는 보고서가 Reporting API v0에서와 같이 일괄 처리되지 않기 때문입니다. 따라서 애플리케이션 개발자가 Reporting API v1로 이전을 시작하면 보고서 수 는 비슷하게 유지되지만 엔드포인트 서버에 대한 요청 볼륨 은 증가합니다.

애플리케이션 개발자: `Reporting-Endpoints` (v1)로 이전

어떻게 해야 할까요?

새로운 Reporting API (v1)를 사용하면 다음과 같은 여러 이점이 있습니다. ✅

브라우저 신호가 긍정적입니다. 즉, Chrome 및 Edge에서만 지원되는 v0과 달리 v1은 교차 브라우저 지원이 예상됩니다.
API가 더 간결합니다.
새로운 Reporting API (v1)를 중심으로 도구가 개발되고 있습니다.

이를 기준으로 보면 다음과 같습니다.

사이트에서 이미 Report-To 헤더와 함께 Reporting API v0을 사용하는 경우 Reporting API v1로 이전합니다 (이전 단계 참고). 사이트에서 이미 콘텐츠 보안 정책 위반에 대한 보고 기능을 사용하는 경우 CSP 보고의 구체적인 이전 단계를 확인하세요.
사이트에서 아직 Reporting API를 사용하지 않고 지금 보고 기능을 추가하는 경우: 새로운 Reporting API (v1) (Reporting-Endpoints 헤더)를 사용합니다. 한 가지 예외가 있습니다. 네트워크 오류 로깅을 사용해야 하는 경우 Report-To (v0)를 사용합니다. Reporting API v1에서는 현재 네트워크 오류 로깅이 지원되지 않습니다. 네트워크 오류 로깅을 위한 새로운 메커니즘이 개발될 예정입니다. 이 메커니즘이 제공될 때까지 Reporting API v0을 사용하세요. 다른 보고서 유형 과 함께 네트워크 오류 로깅이 필요한 경우 모두 Report-To (v0)와 Reporting-Endpoints (v1)를 사용합니다. v0 은 네트워크 오류 로깅을 제공하고 v1은 다른 모든 유형의 보고서를 제공합니다.

이전 단계

이전의 목표는 v0에서 가져오던 보고서를 잃지 않는 것 입니다.

1단계(지금 실행): 두 헤더(Report-To(v0) 및 Reporting-Endpoints(v1))를 모두 사용합니다.

이렇게 하면 다음을 얻을 수 있습니다.
- Reporting-Endpoints (v1) 덕분에 최신 Chrome 및 Edge 클라이언트의 보고서
- Report-To (v0) 덕분에 이전 Chrome 및 Edge 클라이언트의 보고서
Reporting-Endpoints를 지원하는 브라우저 인스턴스는 Reporting-Endpoints를 사용하고 지원하지 않는 인스턴스는 Report-To로 대체됩니다. 요청 및 보고서 형식은 v0과 v1에서 동일합니다.
2단계 (지금 실행): 보고서를 생성할 수 있는 모든 응답에 Reporting-Endpoints 헤더가 설정되어 있는지 확인합니다.

v0을 사용하면 일부 응답에만 보고 엔드포인트를 설정할 수 있으며 해당 출처의 다른 문서(페이지)는 이 '주변' 엔드포인트를 사용합니다. v1에서는 범위 지정의 차이로 인해 보고서를 생성할 수 있는 모든 응답에 Reporting-Endpoints 헤더를 설정해야 합니다.
3단계 (나중에 시작): 모든 사용자 또는 대부분의 사용자가 최신 Chrome 또는 Edge 설치 (96 이상)로 업데이트한 후 Report-To (v0)를 삭제하고 Reporting-Endpoints만 유지합니다.

한 가지 예외: 네트워크 오류 로깅 보고서가 필요한 경우 네트워크 오류 로깅을 위한 새로운 메커니즘이 마련될 때까지 Report-To를 유지합니다.

이전 Cookbook에서 코드 예시를 참고하세요.

CSP 보고의 이전 단계

콘텐츠 보안 정책 위반 보고서를 구성하는 방법에는 두 가지가 있습니다.

report-uri 지시어를 통해 CSP 헤더만 사용합니다. Chrome, Firefox, Safari, Edge에서 광범위한 브라우저 지원이 제공됩니다. 보고서는 콘텐츠 유형 application/csp-report와 함께 전송되며 CSP에 특정한 형식을 갖습니다. 이러한 보고서를 'CSP 수준 2 보고서'라고 하며 Reporting API에 의존하지 않습니다.
Reporting API를 사용합니다. 즉, Report-To 헤더 (기존) 또는 최신 Reporting-Endpoints (v1)를 사용합니다. Chrome 및 Edge에서만 지원됩니다. 보고서 요청은 다른 Reporting API 요청과 동일한 형식과 동일한 콘텐츠 유형 application/reports+json을 갖습니다.

첫 번째 접근 방식 (report-uri만 사용)은 더 이상 권장되지 않습니다 두 번째 접근 방식을 사용하면 몇 가지 이점이 있습니다. 특히 모든 보고서 유형에 대한 보고를 설정하는 단일 방법을 사용하고 일반 엔드포인트를 설정할 수 있습니다. Reporting API를 통해 생성된 모든 보고서 요청 (CSP 및 기타)은 동일한 형식 application/reports+json을 갖기 때문입니다.

하지만 몇몇 브라우저만 report-to를 지원합니다. 따라서 여러 브라우저에서 CSP 위반 보고서를 가져오려면 Reporting API 접근 방식 (Report-To 또는 더 나은 Reporting-Endpoints)과 함께 report-uri를 유지하는 것이 좋습니다. report-uri와 report-to를 인식하는 브라우저에서 report-to가 있으면 report-uri가 무시됩니다. report-uri만 인식하는 브라우저에서는 report-uri만 고려됩니다.

1단계 (지금 실행): 아직 추가하지 않은 경우 report-uri와 함께 report-to를 추가합니다. report-uri만 지원하는 브라우저 (Firefox)는 report-uri를 사용하고 report-to도 지원하는 브라우저(Chrome, Edge)는 report-to를 사용합니다. report-to에서 사용할 명명된 엔드포인트를 지정하려면 Report-To와 Reporting-Endpoints 헤더를 모두 사용합니다. 이렇게 하면 이전 및 최신 Chrome 및 Edge 클라이언트의 보고서를 모두 가져올 수 있습니다.
3단계 (나중에 시작): 모든 사용자 또는 대부분의 사용자가 최신 Chrome 또는 Edge 설치 (96 이상)로 업데이트한 후 Report-To (v0)를 삭제하고 Reporting-Endpoints만 유지합니다. report-uri를 유지하여 report-uri만 지원하는 브라우저의 보고서를 계속 가져옵니다.

CSP 보고 이전의 이러한 단계에 관한 코드 예시를 참고하세요.

이전: 코드 예시

개요

기존 Reporting API (v0)를 사용하여 COOP(Cross-Origin-Opener-Policy 헤더), COEP (Cross-Origin-Embedder-Policy) 또는 문서 정책(Document-Policy 헤더)의 위반 보고서를 가져오는 경우 Reporting API v1로 이전할 때 이러한 정책 헤더 자체를 변경할 필요가 없습니다. 기존 Report-To 헤더에서 새로운 Reporting-Endpoints 헤더로 이전해야 합니다.

기존 Reporting API (v0)를 사용하여 CSP(Content-Security-Policy 헤더)의 위반 보고서를 가져오는 경우 새로운 Reporting API (v1)로 이전하는 과정에서 Content-Security-Policy를 조정해야 할 수 있습니다.

기본 이전

기존 코드 (v0 포함)

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

새로운 코드 (v0과 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" }] }

사이트에 이미 보고 기능이 있는 경우 보고서가 손실되지 않도록 Report-To를 일시적으로만(대부분의 Chrome 및 Edge 클라이언트가 업데이트될 때까지) 유지합니다.

네트워크 오류 로깅이 필요한 경우 네트워크 오류 로깅 대체가 제공될 때까지 Report-To를 유지합니다.

새로운 코드 (v1만 포함)

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

대부분의 Chrome 및 Edge 클라이언트가 업데이트되고 API v1을 지원하면 코드가 다음과 같이 표시될 수 있습니다.

v1을 사용하면 특정 보고서 유형 을 특정 엔드포인트 로 계속 전송할 수 있습니다. 하지만 엔드포인트당 하나의 URL만 사용할 수 있습니다.

모든 페이지 관찰

기존 코드 (v0 포함), 예를 들어 Express 포함

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

v0을 사용하면 일부 응답에만 보고 엔드포인트를 설정할 수 있습니다. 이 출처의 다른 문서 (페이지)는 이러한 주변 엔드포인트를 자동으로 사용합니다. 여기서 "/"에 설정된 엔드포인트는 모든 응답(예: page1)에 사용됩니다.

새로운 코드 (v1 포함), 예를 들어 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(...)
});

v1을 사용하면 보고서를 생성할 수 있는 모든 응답에 Reporting-Endpoints 헤더를 설정해야 합니다.

CSP 보고 이전

기존 코드(report-uri만 포함)

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

report-uri만 사용하는 것은 더 이상 권장되지 않습니다. 코드가 위와 같은 경우 이전하세요. 아래의 새로운 코드 예시 (녹색)를 참고하세요.

더 나은 기존 코드(report-uri 및 Report-To(v0) 헤더의 report-to 지시어 포함)

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

이 코드는 report-uri의 최신 대체인 report-to를 사용하므로 더 좋습니다. 이전 버전과의 호환성을 위해 report-uri를 계속 유지합니다. 여러 브라우저가 report-to 는 지원하지 않지만 report-uri는 지원합니다.

하지만 이 코드는 Reporting API v0 (Report-To 헤더)을 사용하므로 더 좋을 수 있습니다. v1로 이전: 아래의 '새로운 코드' 예시 (녹색)를 참고하세요.

새로운 코드(report-uri 및 Reporting-Endpoints(v1) 헤더의 report-to 지시어 포함)

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

report-to 지시어가 브라우저 간에 지원될 때까지 report-to 지시어와 함께 report-uri 지시어를 유지합니다. 브라우저 호환성 표를 참고하세요.

Reporting-Endpoints와 함께 Report-To를 일시적으로 유지합니다. 대부분의 Chrome 및 Edge 방문자가 96 이상의 브라우저 버전으로 업그레이드하면 Report-To를 삭제합니다.

추가 자료

Reporting API로 웹 애플리케이션 모니터링 (Reporting API에 관한 기본 게시물)
사양: 기존 Reporting API (v0)
사양: 새로운 Reporting API (v1)

이 기고문에 관한 검토와 제안을 해 주신 이언 클레랜드, 기타무라 에이지, 밀리카 미하일리아에게 감사의 말씀을 전합니다.