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 gerçekleşen hatalar hakkında sizi bilgilendirir. Tarayıcı müdahaleleri, tarayıcı kilitlenmeleri, İçerik Güvenliği Politikası ihlalleri, COOP/COEP ihlalleri, desteği sonlandırılan özelliklerle ilgili uyarılar ve daha fazlası hakkında bilgi edinebilirsiniz.

Reporting API'nin yeni bir sürümü kullanıma sunuldu. Yeni API daha basittir ve tarayıcılarda desteklenme olasılığı daha yüksektir.

Özet

Site geliştiricileri

Siteniz için raporlama işleviniz varsa: Yeni başlığı (Reporting-Endpoints) kullanarak v1'e geçin ancak eski başlığı bir süre daha kullanmaya devam edin (Report-To). Taşıma: örnek kod bölümüne bakın.

Sitenize şu anda raporlama işlevi 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 hizmeti kullanıyor veya kendi işletim sisteminizi kullanıyorsanız siz veya harici geliştiriciler Reporting API v1'e (Reporting-Endpoints üst bilgisi) geçerken daha fazla trafik bekleyebilirsiniz.

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

Ağ Hatası Günlük Kaydı

Ağ hatası günlüğü için yeni bir mekanizma geliştirilecek. Bu kullanıma sunulduğunda Reporting API v0'dan bu yeni mekanizmaya geçin.

Demo ve kod

• Demo sitesi: yeni Reporting API (v1)
• Demo site kodu

Sürüm 0 ile 1 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.

• Her iki API de aynı rapor türlerini destekler, ancak bir istisna vardır: v1, Ağ Hatası raporlarını desteklemez. Daha fazla bilgi için taşıma adımlarına bakın.
• v0 desteklenmez ve tarayıcılarda desteklenmeyecektir. v1'in gelecekte birden fazla tarayıcıda desteklenme olasılığı daha yüksektir.

Değişmeyenler

• Raporların biçimi ve yapısı değişmemiştir.
• 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ın belirli rapor türleriyle eşlenmesi hem v0 hem de v1 sürümünde desteklenir.
• default uç noktasının rolü değişmez.

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

v0 ile v1 arasındaki tüm farklar

Uç nokta geliştiricileri: Daha fazla trafik bekleyin

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

Bunun nedeni, raporların Reporting API v0'da olduğu gibi Reporting API v1 ile toplu olarak gönderilmemesidir. Bu nedenle, uygulama geliştiriciler Reporting API v1'e geçiş yapmaya başladığında rapor sayısı benzer kalacak ancak uç nokta sunucusuna yapılan istek hacmi artacaktır.

Uygulama geliştiriciler: Reporting-Endpoints'e (v1) taşıma

Bu durumda ne yapmanız gerekir?

Yeni Reporting API'yi (v1) kullanmanın çeşitli avantajları vardır ✅:

• Tarayıcı sinyalleri pozitiftir. Yani, v1 için (yalnızca Chrome ve Edge'de desteklenen v0'ın aksine) tarayıcılar arası destek beklenebilir.
• API daha basittir.
• Araçlar, yeni Reporting API (v1) etrafında geliştirilmektedir.

Bu nedenle:

• Sitenizde Report-To başlığıyla birlikte Reporting API v0 kullanılıyorsa Reporting API v1'e geçin (taşıma adımlarına bakın). Sitenizde İçerik Güvenliği Politikası ihlalleri için raporlama işlevi zaten kullanılıyorsa CSP raporlaması için taşıma adımlarını kontrol edin.
• Sitenizde Reporting API kullanılmıyorsa ve raporlama işlevi ekleyecekseniz: yeni Reporting API'yi (v1) (Reporting-Endpoints başlığını) kullanın. Bunun bir istisnası vardır: Ağ Hatası Günlük Kaydı 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üğe Kaydetme için yeni bir mekanizma geliştirilecek⏤. Bu mekanizma kullanıma sunulana kadar Reporting API v0'u kullanın. Diğer rapor türlerinin yanında Ağ Hatası Günlüğe Kaydetme özelliğine ihtiyacınız varsa Report-To (v0) ve Reporting-Endpoints (v1) sürümlerini aynı anda kullanın. v0 sürümünde Ağ Hatası Günlüğe Kaydetme özelliğini, v1 sürümünde ise diğer tüm türlerde raporları bulabilirsiniz.

Taşıma adımları

Bu taşıma işleminde amacınız, v0 sürümünde aldığınız raporları kaybetmemektir.

1. 1. Adım (şimdi yapın): Hem Report-To (v0) hem de Reporting-Endpoints (v1) üstbilgilerini kullanın.

   Bu sayede:

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

   Reporting-Endpoints'ü destekleyen tarayıcı örnekleri Reporting-Endpoints'ü, desteklemeyen örnekler ise Report-To'e geçer. İstek ve rapor biçimi, v0 ve v1 için aynıdır.

2. 2. adım (hemen yapın): Rapor oluşturabilecek tüm yanıtlarda Reporting-Endpoints üstbilgisinin ayarlandığından emin olun.

   v0 ile yalnızca bazı yanıtlarda raporlama uç noktaları ayarlamayı tercih edebilirsiniz. Bu kaynaktaki diğer dokümanlar (sayfalar) bu "ambiyans" uç noktasını kullanır. 1. sürümde, kapsamdaki farklılık nedeniyle rapor oluşturabilecek tüm yanıtlarda Reporting-Endpoints üstbilgisini ayarlamanız gerekir.

3. 3. Adım (daha sonra başlatın): Kullanıcılarınızın tümü veya çoğu daha sonra Chrome ya da Edge yüklemelerine (96 ve sonraki sürümler) güncelleme yaptığında Report-To (v0) uygulamasını kaldırın ve yalnızca Reporting-Endpoints sürümünü saklayı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 uygulanana kadar Report-To değerini kullanın.

Taşıma rehberindeki kod örneklerine bakın.

CSP raporlaması için taşıma adımları

Content-Security-Policy ihlali raporları iki şekilde yapılandırılabilir:

• report-uri yönergesi aracılığıyla yalnızca CSP üst bilgisiyle. Bu özellik Chrome, Firefox, Safari ve Edge'de geniş tarayıcı desteğine sahiptir. Raporlar application/csp-report içerik türüyle gönderilir ve CSP'ye özgü bir biçime sahiptir. Bu raporlara "CSP 2. Katman Raporları" denir ve Reporting API'ye dayanmaz.
• Reporting API'de bu, Report-To başlığı (eski) veya daha yeni Reporting-Endpoints (v1) üzerinden yapılır. Bu özellik yalnızca Chrome ve Edge'de desteklenir. Rapor istekleri, diğer Reporting API istekleriyle aynı biçime sahiptir ve aynı içerik türüne (application/reports+json) sahiptir.

İlk yaklaşımın (yalnızca report-uri) kullanılması artık önerilmez. İkinci yaklaşımın kullanılmasının ise birkaç avantajı vardır. Özellikle, tüm rapor türleri için raporlamayı tek bir yöntemle ayarlamanızı ve genel bir uç nokta belirlemenizi sağlar (çünkü Reporting API⏤CSP ve diğerleri⏤ aracılığıyla oluşturulan tüm rapor istekleri aynı biçime sahiptir application/reports+json.

Ancak report-to özelliğini yalnızca birkaç tarayıcı destekler. Bu nedenle, birden fazla tarayıcıdan CSP ihlali raporu almak için Reporting API yaklaşımının (Report-To veya daha iyisi Reporting-Endpoints) yanı sıra report-uri'ü de kullanmaya devam etmeniz önerilir. report-uri ve report-to'u tanıyan bir tarayıcıda report-to varsa report-uri yoksayılır. Yalnızca report-uri'ü tanıyan bir tarayıcıda yalnızca report-uri dikkate alınır.

1. 1. Adım (şimdi yapın): Henüz eklemediyseniz report-uri öğesinin yanına report-to ekleyin. Yalnızca report-uri'ü (Firefox) destekleyen tarayıcılar report-uri'ü, report-to'ü de destekleyen tarayıcılar (Chrome, Edge) ise report-to'ü 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. Bu sayede hem eski hem de yeni Chrome ve Edge istemcilerinden rapor alırsınız.

2. 3. adım (daha sonra başlayın): Kullanıcılarınızın tümü veya çoğu daha yeni Chrome ya da Edge sürümlerine (96 ve sonraki sürümler) güncellendikten sonra Report-To (v0) öğesini kaldırın ve yalnızca Reporting-Endpoints öğesini bırakın. Yalnızca destekleyen tarayıcılar hakkında raporlar almaya devam etmek için report-uri komutunu tutun.

CSP raporlama taşıma bölümünde bu adımlarla ilgili kod örneklerini inceleyin.

Taşıma: örnek kod

Genel Bakış

COOP (Cross-Origin-Opener-Policy üstbilgisi), COEP (Cross-Origin-Embedder-Policy) veya doküman politikası (Document-Policy üstbilgisi) ihlal raporları almak için eski Reporting API'yi (v0) kullanıyorsanız: Reporting API v1'e geçiş yaparken bu politika üstbilgilerinin kendisini değiştirmeniz gerekmez. Eski Report-To başlığından yeni Reporting-Endpoints başlığına geçmeniz gerekir.

Bir CSP (Content-Security-Policy başlığı) için ihlal raporları almak üzere eski Reporting API'yi (v0) kullanıyorsanız yeni Reporting API'ye (v1) geçişiniz kapsamında Content-Security-Policy'nüzü değiştirmeniz 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"

1. sürümde belirli uç noktalara belirli rapor türleri göndermeye devam edebileceğinizi unutmayın. Ancak uç nokta başına yalnızca bir URL'niz olabilir.

Tüm sayfaları gözlemleme

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 işlemi

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

• Web uygulamanızı Reporting API ile izleme (Reporting API ile ilgili ana yayın)
• Özellik: eski Reporting API (v0)
• Özellik: yeni Reporting API (v1)

Bu makaledeki yorumları ve önerileri için Ian Clelland, Eiji Kitamura ve Milica Mihajlija'ya çok teşekkür ederiz.