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 v0에서 새 메커니즘으로 전환하세요.

데모 및 코드

• 데모 사이트: 새 Reporting API (v1)
• 데모 사이트용 코드

v0과 v1의 차이점

변경되는 사항

• API 노출 영역은 다릅니다.

 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

• 보고서 범위가 다릅니다.

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

변경되지 않는 사항

• 보고서의 형식과 구조는 변경되지 않았습니다.
• 브라우저에서 엔드포인트로 보낸 요청은 Content-type application/reports+json의 POST 요청으로 유지됩니다.
• 특정 엔드포인트를 특정 보고서 유형에 매핑하는 작업은 v0 및 v1 모두에서 지원됩니다.
• default 엔드포인트의 역할은 변경되지 않습니다.

• Reporting API v1은 ReportingObserver에 영향을 주지 않습니다. ReportingObserver는 관찰 가능한 모든 보고서에 계속 액세스할 수 있으며 형식은 동일합니다.

v0과 v1의 모든 차이점

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

자체 서버를 보고 엔드포인트로 설정했거나 보고서 수집기를 서비스로 개발 또는 유지보수하는 경우 해당 엔드포인트로 더 많은 트래픽이 발생할 수 있습니다.

이는 Reporting API v0과 마찬가지로 Reporting API v1에서는 보고서가 일괄 처리되지 않기 때문입니다. 따라서 애플리케이션 개발자가 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. 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. 2단계 (지금 실행): 보고서를 생성할 수 있는 모든 응답에 Reporting-Endpoints 헤더가 설정되어 있는지 확인합니다.

   v0을 사용하면 일부 응답에서만 보고 엔드포인트를 설정할 수 있으며 해당 출처의 다른 문서(페이지)는 이 '대기' 엔드포인트를 사용합니다. v1을 사용하면 범위 지정의 차이로 인해 보고서를 생성할 수 있는 모든 응답에 Reporting-Endpoints 헤더를 설정해야 합니다.

3. 3단계 (나중에 시작): 전체 또는 대부분의 사용자가 최신 Chrome 또는 Edge 설치 (96 이상)로 업데이트하면 Report-To (v0)을 삭제하고 Reporting-Endpoints만 유지합니다.

   한 가지 예외: 네트워크 오류 로깅 보고서가 필요한 경우 네트워크 오류 로깅에 새로운 메커니즘이 적용될 때까지 Report-To를 유지하세요.

이전 설명서에서 코드 예를 참고하세요.

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. 1단계 (지금 실행): 아직 추가하지 않았다면 report-uri와 함께 report-to를 추가합니다. report-uri만 지원하는 브라우저 (Firefox)에서는 report-uri를 사용하고 report-to도 지원하는 브라우저(Chrome, Edge)에서는 report-to를 사용합니다. report-to에서 사용할 이름이 지정된 엔드포인트를 지정하려면 헤더 Report-To 및 Reporting-Endpoints를 모두 사용합니다. 이렇게 하면 이전 및 최신 Chrome 및 Edge 클라이언트 모두에서 보고서를 받을 수 있습니다.

2. 3단계 (나중에 시작): 전체 또는 대부분의 사용자가 최신 Chrome 또는 Edge 설치 (96 이상)로 업데이트하면 Report-To (v0)을 삭제하고 Reporting-Endpoints만 유지합니다. 이 기능만 지원하는 브라우저에 관한 보고서를 계속 받을 수 있도록 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를 조정해야 할 수 있습니다.

기본 이전

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"

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

모든 페이지 관찰

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

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

추가 자료

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

Nine Koepfer / @enka80의 히어로 이미지 Unsplash 수정 이 기사에 대한 검토와 제안을 주신 이안 클레랜드, 키타무라 에이지, 밀리카 미하즐리야 씨께 감사의 말씀을 전합니다.