Reporting API v1'e geçin

Reporting API'nin yeni bir sürümü mevcut. Daha gizlidir ve tarayıcılarda desteklenme olasılığı daha yüksektir.

Maud Nalpas

Reporting API, ziyaretçiler sitenizi kullanırken sitenizde oluşan hatalar hakkında sizi bilgilendirir. Tarayıcı müdahaleleri, tarayıcı kilitlenmeleri, İçerik Güvenliği Politikası ihlalleri, COOP/COEP ihlalleri, kullanımdan kaldırma uyarıları ve daha fazlası hakkında bilgi sahibi olmanızı sağlar.

Reporting API'nin yeni bir sürümü mevcut. Yeni API daha yalındır ve tarayıcılarda desteklenme olasılığı daha yüksektir.

Özet

Site geliştiriciler

Sitenizde zaten raporlama işlevi varsa: Yeni başlığı (Reporting-Endpoints) kullanarak v1'e taşıyın, ancak eski başlığı bir süre (Report-To) kullanın. Taşıma: örnek kod bölümüne bakın.

Sitenize raporlama işlevini şimdi ekliyorsanız: yalnızca yeni başlığı (Reporting-Endpoints) kullanın.

⚠️ Her iki durumda da, rapor oluşturabilecek tüm yanıtlarda Reporting-Endpoints üst bilgisini ayarladığınızdan emin olun.

Raporlama hizmeti geliştiricileri

Bir uç nokta hizmetinin bakımını yapıyor veya kendi hizmetinizi çalıştırıyorsanız siz veya harici geliştiriciler Reporting API v1'e (Reporting-Endpoints başlığı) geçiş yaptıkça daha fazla trafik elde edebilirsiniz.

Ayrıntılar ve örnek kod için okumaya devam edin.

Ağ Hatası Günlük Kaydı

Ağ Hatası Günlük Kaydı için yeni bir mekanizma geliştirilecektir. Bu kullanıma sunulduğunda Reporting API v0'dan bu yeni sisteme geçin.

Demo ve kod

• Demo sitesi: Yeni Reporting API (v1)
• Demo sitesinin kodu

v0 ile v1 arasındaki farklar

Neler değişecek?

• API yüzeyi farklıdır.

 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

• Raporun kapsamı farklıdır.

• Bir istisna dışında her iki API de aynı rapor türlerini destekler: v1, Ağ Hatası raporlarını desteklemez. Daha fazla bilgi için taşıma adımlarını inceleyin.
• v0, tarayıcılar arasında desteklenmez ve desteklenmeyecektir. v1'in gelecekte birden fazla tarayıcıda desteklenme olasılığı daha yüksektir.

Değişmeyen bilgiler

• Raporların biçimi ve yapısı değişmez.
• Tarayıcı tarafından uç noktaya gönderilen istek, Content-type application/reports+json tutarındaki bir POST isteği olarak kalır.
• Belirli uç noktaları belirli rapor türleriyle eşlemek hem v0 hem de v1'de desteklenir.
• default uç noktasının rolü değişmedi.

• Reporting API v1'in ReportingObserver üzerinde herhangi bir etkisi yoktur. ReportingObserver, tüm gözlemlenebilir raporlara erişmeye devam eder ve raporların biçimleri aynıdır.

v0 ile v1 arasındaki tüm farklılıklar

Uç nokta geliştiricileri: Daha fazla trafik bekleyin

Kendi sunucunuzu raporlama uç noktası olarak ayarladıysanız veya hizmet olarak bir rapor toplayıcısı geliştiriyor ya da sürdürüyorsanız bu uç noktaya daha fazla trafik gelmesini bekleyin.

Bunun nedeni, raporların Reporting API v1'de olduğu gibi Reporting API v1 ile toplu olarak işlenmemesidir. Bu nedenle, uygulama geliştiricileri Reporting API v1'e geçmeye başladıkça rapor sayısı benzer olacaktır ancak uç nokta sunucusuna gönderilen istek hacmi artacaktır.

Uygulama geliştiriciler: Reporting-Endpoints sürümüne (v1) geçiş

Bu durumda ne yapmanız gerekir?

Yeni Reporting API'yi (v1) kullanmanın birçok avantajı vardır ✅:

• Tarayıcı sinyalleri pozitiftir, yani v1 için tarayıcılar arası destek beklenebilir (yalnızca Chrome ve Edge'de desteklenen v0'dan farklı olarak).
• API daha yalındır.
• Araçlar, yeni Reporting API (v1) çerçevesinde geliştirilmektedir.

Buradan yola çıkarak:

• Sitenizde Report-To başlığıyla Reporting API v0 zaten kullanılıyorsa Reporting API v1'e geçiş yapın (taşıma adımlarına göz atın). Sitenizde İçerik Güvenliği Politikası ihlalleri için raporlama işlevi zaten kullanılıyorsa İGP raporlaması için belirli taşıma adımlarını kontrol edin.
• Sitenizde halihazırda Reporting API kullanılmıyorsa ve şimdi raporlama işlevi ekliyorsanız: yeni Reporting API'yi (v1) kullanın (Reporting-Endpoints başlığı). Bunun bir istisnası vardır: Ağ Hatası Günlük Kaydı'nı kullanmanız gerekiyorsa Report-To (v0) kullanın. Ağ Hatası Günlük Kaydı, şu anda Reporting API v1'de desteklenmemektedir. Ağ Hatası Günlük Kaydı için yeni bir mekanizma geliştirilecektir ⏤şuna kadar Reporting API v0'ı kullanın. Diğer rapor türlerinin yanı sıra Ağ Hatası Günlük Kaydı'na ihtiyacınız varsa Report-To (v0) ve Reporting-Endpoints (v1) her ikisini de kullanın. v0, Ağ Hatası Günlük Kaydı'nı, v1 ise diğer tüm türlerin raporlarını sunar.

Taşıma adımları

Bu taşıma işleminde amacınız, v0 ile aldığınız raporları kaybetmemek.

1. 1. Adım (şimdi yapın): İki başlığı da kullanın: Report-To (v0) ve Reporting-Endpoints (v1).

   Bununla, şunları elde edersiniz:

   • Reporting-Endpoints (v1) sayesinde yeni Chrome ve Edge istemcilerinden raporlar.
   • Report-To (v0) sayesinde eski Chrome ve Edge istemcilerinden gelen raporlar.

   Reporting-Endpoints özelliğini destekleyen tarayıcı örnekleri Reporting-Endpoints kullanır. Bunu desteklemeyen örnekler ise Report-To kullanır. İstek ve rapor biçimi, v0 ve v1 için aynıdır.

2. 2. Adım (şimdi yapın): Rapor oluşturabilecek tüm yanıtlarda Reporting-Endpoints üst bilgisinin ayarlandığından emin olun.

   v0 sürümüyle yalnızca bazı yanıtlarda raporlama uç noktaları belirleyebilirsiniz ve söz konusu kaynaktaki diğer dokümanlar (sayfalar) bu "ambiyans" uç noktasını kullanır. v1'de kapsam oluşturmadaki farklılıktan dolayı, rapor oluşturabilecek tüm yanıtlarda Reporting-Endpoints başlığını ayarlamanız gerekir.

3. 3. Adım (daha sonra başlayın): Kullanıcılarınızın tümü veya çoğu, daha yeni Chrome veya Edge yüklemeleri (96 ve üzeri) sürümüne güncelledikten sonra, Report-To (v0) uygulamasını kaldırın ve yalnızca Reporting-Endpoints kullanın.

   Bir istisna: Ağ Hatası Günlük Kaydı raporlarına ihtiyacınız varsa Ağ Hatası Günlük Kaydı için yeni bir mekanizma oluşturulana kadar Report-To politikasını kullanın.

Taşıma kılavuzundaki kod örneklerini inceleyin.

CSP raporlaması için geçiş adımları

Content-Security-Policy ihlal raporlarını iki şekilde yapılandırabilirsiniz:

• report-uri yönergesi aracılığıyla yalnızca CSP başlığıyla. Chrome, Firefox, Safari ve Edge'de kapsamlı tarayıcı desteği var. Raporlar application/csp-report içerik türüyle ve CSP'ye özel bir biçimde gönderilir. Bu raporlar "CSP Düzey 2 Raporlar" olarak adlandırılır ve Reporting API'yi temel almaz.
• Reporting API ile Report-To başlığı (eski) veya daha yenisi Reporting-Endpoints (v1) üzerinden iletilir. Bu özellik yalnızca Chrome ve Edge'de desteklenir. Rapor istekleri, diğer Reporting API istekleriyle aynı biçime ve aynı içerik türüne sahiptir: application/reports+json.

İlk yaklaşımın (yalnızca report-uri) kullanılması artık önerilmemektedir. İkinci yaklaşımın da birkaç avantajı vardır. Özellikle, tüm rapor türleri için raporlamayı tek bir şekilde ayarlamanıza ve genel bir uç nokta ayarlamanıza olanak tanır (bunun nedeni, Reporting API ⏤CSP ve diğerlerinin ⏤ aynı application/reports+json biçimine sahip olmasıdır).

Ancak yalnızca birkaç tarayıcı report-to'yi destekler. Bu nedenle, birden çok tarayıcıdan İGP ihlal raporu almak için report-uri hizmetini Reporting API yaklaşımıyla (Report-To veya daha iyisi, Reporting-Endpoints) birlikte tutmanız önerilir. report-uri ve report-to öğelerini tanıyan bir tarayıcıda report-to varsa report-uri yoksayılır. Yalnızca report-uri öğesini tanıyan bir tarayıcıda sadece report-uri dikkate alınır.

1. 1. Adım (şimdi yapın): Henüz eklemediyseniz report-uri ile birlikte report-to ekleyin. Yalnızca report-uri (Firefox) desteği olan tarayıcılar report-uri protokolünü, report-to(Chrome, Edge) destekleyen tarayıcılar da report-to biçimini kullanır. report-to içinde kullanacağınız adlandırılmış uç noktaları belirtmek için hem Report-To hem de Reporting-Endpoints başlıklarını kullanın. Böylece hem eski hem de yeni Chrome ve Edge istemcilerinden rapor alabilirsiniz.

2. 3. Adım (daha sonra başlayın): Kullanıcılarınızın tümü veya çoğu, daha yeni Chrome veya Edge yüklemeleri (96 ve üzeri) sürümüne güncelledikten sonra, Report-To (v0) uygulamasını kaldırın ve yalnızca Reporting-Endpoints kullanın. Yalnızca destekleyen tarayıcılarla ilgili raporları almaya devam etmek için report-uri öğesini tutun.

CSP raporlamasını taşıma bölümünde, bu adımlara yönelik kod örneklerini inceleyin.

Taşıma: örnek kod

Genel bakış

Bir COOP (Cross-Origin-Opener-Policy başlığı), COEP (Cross-Origin-Embedder-Policy) veya doküman politikası (Document-Policy başlığı) ile ilgili ihlal raporları almak için eski Reporting API'yi (v0) kullanıyorsanız: Reporting API v1'e geçerken bu politika başlıklarını kendi başınıza değiştirmeniz gerekmez. Bunun için eski Report-To başlığından yeni Reporting-Endpoints başlığına geçmeniz gerekir.

Bir CSP (Content-Security-Policy başlığı) ile ilgili ihlal raporları almak için eski Reporting API'yi (v0) kullanıyorsanız yeni Reporting API'ye (v1) geçişinizin bir parçası olarak Content-Security-Policy üzerinde ince ayar yapmanız gerekebilir.

Temel taşıma

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 ile belirli rapor türlerini belirli uç noktalara göndermeye devam edebileceğinizi unutmayın. Ancak uç nokta başına yalnızca bir URL'niz olabilir.

Tüm sayfalar gözlemleniyor

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 raporlama taşıma

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

Daha fazla bilgi

• Reporting API ile web uygulamanızı izleme (Reporting API'deki ana yayın)
• Spesifikasyon: eski Reporting API (v0)
• Spesifikasyon: yeni Reporting API (v1)

Nine Koepfer / @enka80 tarafından Unsplash'teki hero resim düzenlendi. Bu makaledeki inceleme ve önerilerinden dolayı Ian Clelland, Eiji Kitamura ve Milica Mihajlija'ya çok teşekkür ederiz.