Reporting API v1'e geçin

Reporting API'nin yeni bir sürümü kullanıma sunuldu. 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 raporlama işlevi eklemek istiyorsanız: Yalnızca yeni başlığı (Reporting-Endpoints) kullanın.

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

Raporlama hizmeti geliştiricileri

Bir uç nokta hizmeti sağlıyorsanız veya kendi hizmetinizi işletiyorsanız siz veya harici geliştiriciler Reporting API v1'e (Reporting-Endpoints başlığı) geçiş yaptığınızda daha fazla trafik alabilirsiniz.

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 özellik kullanıma sunulduğunda Reporting API v0'dan bu yeni mekanizmaya geçin.

Demo ve kod

• Demo sitesi: yeni Reporting API (v1)
• Demo sitenin 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. Bunun tek istisnası, 1. sürümün ağ hatası raporlarını desteklememesidir. Daha fazla bilgi için taşıma adımlarını inceleyin.
• 0 sürümü tarayıcılarda desteklenmiyor ve desteklenmeyecek. 1 sürümünün gelecekte birden fazla tarayıcıda desteklenmesinin daha olasıdır.

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 için 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, ReportingObserver'u etkilemez. 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 olumlu. Bu, sürüm 1 için tarayıcılar arası desteğin beklenebileceği anlamına gelir (yalnızca Chrome ve Edge'de desteklenen sürüm 0'dan farklı olarak).
• API daha basittir.
• Araçlar, yeni Reporting API (v1) için 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 tek bir istisnası vardır: Ağ Hatası Günlük Kaydını kullanmanız gerekiyorsa Report-To (v0) sürümünü kullanın. Ağ hatası günlüğü, şu anda Reporting API v1'de desteklenmiyor. 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 (hemen yapın): Report-To (v0) ve Reporting-Endpoints (v1) olmak üzere her iki üstbilgeyi de kullanın.

   Bu sayede:

   • Reporting-Endpoints (v1) sayesinde daha yeni Chrome ve Edge istemcilerinden gelen 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.

   0 sürümü ile yalnızca bazı yanıtlarda raporlama uç noktalarını ayarlayabilirsiniz. Bu kaynaktaki diğer dokümanlar (sayfalar) bu "çevresel" uç noktasını kullanır. 1. sürümde, kapsamdaki fark nedeniyle rapor oluşturabilecek tüm yanıtlarda Reporting-Endpoints üstbilgisini 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 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.

   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 ve application/reports+json içerik türüne 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'yi 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 (hemen yapın): Henüz eklemediyseniz report-uri ile birlikte report-to öğesini de 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'te 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 report-uri'i destekleyen tarayıcılar için rapor almaya devam etmek istiyorsanız report-uri'i etkin durumda 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

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)
• Özellik: eski Reporting API (v0)
• Özellik: yeni Reporting API (v1)

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