Reporting API v1'e geçin

Raporlama API'sinin yeni bir sürümü kullanıma sunuldu. Bu yöntem daha gizlidir ve tarayıcılar arasında desteklenme olasılığı daha yüksektir.

Maud Nalpas

Dikkat: Bu yayında, Reporting API'nin yeni sürümüne (v1) nasıl geçileceği açıklanmaktadır. Reporting API'yi yeni kullanmaya başladıysanız veya ayrıntılı kullanım örneklerine ihtiyacınız varsa bunun yerine Reporting API ile ilgili ana gönderiye gidin.

Reporting API, ziyaretçiler sitenizi kullanırken sitenizde oluşan hatalar hakkında sizi bilgilendirir. Tarayıcı müdahaleleri, tarayıcı çökmeleri, İçerik Güvenliği Politikası ihlalleri, COOP/COEP ihlalleri, desteği sonlandırılan özelliklerle ilgili uyarılar ve daha fazlası hakkında bilgi edinmenizi sağlar.

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

Not: Eski Reporting API'nin adı Reporting API v0'dır. Yeni Reporting API'nin adı Reporting API v1'dir.

Özet

Site geliştiricileri

Siteniz için zaten 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 başlıklı makaleyi inceleyin.

Sitenize raporlama işlevini yeni ekliyorsanı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 hizmetini sürdürüyorsanız veya kendi uç nokta hizmetinizi işletiyorsanız siz ya da harici geliştiriciler Reporting API v1'e (Reporting-Endpoints üstbilgisi) geçiş yaptığında daha fazla trafik bekleyebilirsiniz.

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

Ağ Hatası Günlüğü

Dikkat: Network Error Logging'i kullanıyorsanız Report-To (v0) kullanmaya devam edin. Çünkü Network Error Logging, Reporting API v1'de desteklenmez.

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

Demo ve kod

• Demo sitesi: yeni raporlama API'si (v1)
• Demo sitesinin kodu

v0 ile v1 arasındaki farklar

Neler değişecek?

• API yüzeyi farklıdır.

v0 (eski)

 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, adlandırılmış uç nokta gruplarını yapılandırmak için Report-To başlığını, bu uç nokta gruplarına referans vermek için diğer başlıklardaki report-to yönergesini kullanır.

v1 (yeni)

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

v1, adlandırılmış uç noktaları yapılandırmak için Reporting-Endpoints başlığını kullanır. v0 gibi, bu uç nokta gruplarına referans vermek için diğer üstbilgilerde report-to yönergesini kullanır.

• Raporun kapsamı farklıdır.

v0 (eski)

v0 ile yalnızca bazı yanıtlarda raporlama uç noktaları ayarlayabilirsiniz. Bu kaynakta bulunan diğer belgeler (sayfalar) otomatik olarak bu ortam uç noktalarını kullanır.

v1 (yeni)

v1'de, rapor oluşturabilecek tüm yanıtlarda Reporting-Endpoints üstbilgisini ayarlamanız gerekir.

• Her iki API de aynı rapor türlerini destekler. Tek istisna, v1'in Ağ Hatası raporlarını desteklememesidir. Daha fazla bilgi için taşıma adımları başlıklı makaleyi inceleyin.
• v0, tarayıcılar arasında desteklenmemektedir ve gelecekte de desteklenmeyecektir. v1'in ise gelecekte birden fazla tarayıcıda desteklenmesi daha olasıdır.

Değişmeyenler

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

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

v0 ile v1 arasındaki tüm farklar

	Eski Reporting API (v0) Report-To header	Yeni Reporting API (v1) Reporting-Endpoints header
Tarayıcı desteği	Chrome 69 ve sonraki sürümler ile Edge 69 ve sonraki sürümler.	Chrome 96 ve sonraki sürümler ile Edge 96 ve sonraki sürümler. Firefox desteklenir. Safari itiraz etmez. Tarayıcı sinyallerine bakın.
Uç noktalar	Raporları birden fazla rapor toplayıcıya (uç nokta grubu başına birden fazla URL tanımlanır) gönderir.	Raporları belirli rapor toplayıcılara gönderir (uç nokta başına yalnızca bir URL tanımlanır).
API yüzeyi	Adlandırılmış uç nokta gruplarını yapılandırmak için `Report-To` üstbilgisini kullanır.	Adlandırılmış endpoints yapılandırmak için `Reporting-Endpoints` başlığını kullanır.
Bu API ile oluşturulabilecek rapor türleri	Kullanımdan Kaldırma Müdahale Kaza COOP/COEP İçerik Güvenliği Politikası Düzeyi 3 (İGP Düzeyi 3) Ağ Hatası Günlüğü (NEL) Reporting API yayınındaki rapor türleri hakkında daha fazla bilgi edinin.	Ağ Hatası Günlüğü (NEL): Bu, yeni Reporting API'de (v1) desteklenmez dışında değişmemiştir.
Rapor kapsamı	Kaynağınıza aitmiş gibi ele almasını sağlayan teknoloji. Bir dokümanın Report-To üstbilgisi, aynı kaynaktan gelen diğer dokümanları (sayfaları) etkiler. Bir raporun url alanı, belgeye göre değişmeye devam eder.	Doküman. Bir dokümanın Reporting-Endpoints üst bilgisi yalnızca o dokümanı etkiler. Bir raporun url alanı, belgeye göre değişmeye devam eder.
Rapor izolasyonu (toplu işleme)	Aynı raporlama uç noktasına sahip ve aynı zamanlarda rapor oluşturan farklı dokümanlar (sayfalar) veya siteler/kaynaklar birlikte gönderilir. Bu öğeler, raporlama uç noktasına aynı mesajda gönderilir.	Farklı dokümanlardan (sayfalar) gelen raporlar hiçbir zaman birlikte gönderilmez. Aynı kaynaktan gelen iki doküman (sayfa) aynı uç nokta için aynı anda rapor oluştursa bile bunlar toplu olarak işlenmez. Bu, gizlilik saldırılarını azaltmaya yönelik bir mekanizmadır. Aynı dokümandaki (sayfa) raporlar birlikte gönderilebilir.
Yük dengeleme / öncelikler için destek	Evet	Hayır

Uç nokta geliştiricileri: Daha fazla trafik bekleyin

Kendi sunucunuzu bir raporlama uç noktası olarak ayarladıysanız veya hizmet olarak bir rapor toplayıcı geliştiriyor ya da bakımını yapıyorsanız bu uç noktaya daha fazla trafik gelmesini bekleyebilirsiniz.

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ıkça rapor sayısı benzer kalacak ancak uç nokta sunucusuna yapılan isteklerin hacmi artacaktır.

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

Bu durumda ne yapmanız gerekir?

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

• Tarayıcı sinyalleri olumlu. Bu nedenle, v1'in tarayıcılar arası desteği beklenmektedir (yalnızca Chrome ve Edge'de desteklenen v0'ın aksine).
• API daha yalındır.
• Yeni Reporting API (v1) ile ilgili araçlar geliştirilmektedir.

Bu nedenle:

• Sitenizde Report-To üstbilgisiyle 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 bildirme işlevi zaten kullanılıyorsa İGP bildirme ile ilgili belirli taşıma adımlarını kontrol edin.
• Siteniz henüz Reporting API'yi kullanmıyorsa ve şimdi raporlama işlevi ekliyorsanız: Yeni Reporting API'yi (v1) (Reporting-Endpoints üstbilgisi) kullanın. Bu durumun bir istisnası vardır: Ağ Hatası Günlüğü'nü kullanmanız gerekiyorsa Report-To (v0) sürümünü kullanın. Ağ Hatası Günlüğü, Reporting API v1'de şu anda desteklenmemektedir. Ağ Hatası Günlüğü için yeni bir mekanizma geliştirilecek. Bu mekanizma kullanıma sunulana kadar Reporting API v0'ı kullanın. Diğer rapor türlerinin yanı sıra Ağ Hatası Günlüğü'ne ihtiyacınız varsa Report-To (v0) ve Reporting-Endpoints (v1) her ikisini de kullanın. v0, Ağ Hatası Günlüğü'nü, v1 ise diğer tüm rapor türlerini sağlar.

Taşıma adımları

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

Not: Reporting API v0'ı yalnızca Chrome ve Edge desteklediğinden v1'e geçişiniz sırasında diğer tarayıcılara odaklanmanız gerekmez. Ancak daha geniş tarayıcı desteğinin gelebileceğini unutmayın. Şu anda bu tarayıcılar için izleme hatası bulunmamaktadır ancak bu durum değişebilir.

1. 1. adım (hemen yapın): Hem Report-To (v0) hem de Reporting-Endpoints (v1) üstbilgilerini 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 özelliğini destekleyen tarayıcı örnekleri Reporting-Endpoints özelliğini kullanır. Bu özelliği desteklemeyen örnekler ise Report-To özelliğine geri döner. İ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ı seçebiliyordunuz ve bu kaynakta bulunan diğer dokümanlar (sayfalar) bu "ortam" uç noktasını kullanıyordu. Kapsamdaki farklılık nedeniyle v1'de 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 tamamı veya çoğu daha sonraki Chrome ya da Edge yüklemelerine (96 ve sonraki sürümler) güncellediğinde Report-To (v0) öğesini kaldırın ve yalnızca Reporting-Endpoints öğesini tutun.

   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 kullanılana kadar Report-To simgesini koruyun.

Taşıma yemek kitabındaki kod örneklerine bakın.

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

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

• Yalnızca report-uri yönergesi aracılığıyla CSP üst bilgisiyle. Bu özellik; Chrome, Firefox, Safari ve Edge gibi birçok tarayıcıda desteklenir. Raporlar, içerik türü application/csp-report ile gönderilir ve CSP'ye özgü bir biçime sahiptir. Bu raporlara "CSP Düzeyi 2 Raporları" denir ve Reporting API'yi kullanmazlar.
• Reporting API ile bu, Report-To üstbilgisi (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 aynı içerik türüne application/reports+json sahiptir.

İlk yaklaşımı (yalnızca report-uri) kullanmak artık önerilmemektedir. İkinci yaklaşımı kullanmanın ise bazı avantajları vardır. Özellikle, tüm rapor türleri için raporlamayı ayarlamak üzere tek bir yöntem kullanmanıza ve genel bir uç nokta ayarlamanıza olanak tanır (çünkü Reporting API⏤CSP ve diğerleri⏤aracılığıyla oluşturulan tüm rapor istekleri aynı biçime sahiptir application/reports+json).

Ancak yalnızca birkaç tarayıcı report-to'ı destekler. Bu nedenle, birden fazla tarayıcıdan CSP ihlali raporları almak için report-uri'yı Reporting API yaklaşımı (Report-To veya daha iyi, Reporting-Endpoints) ile birlikte kullanmanız önerilir. report-uri ve report-to'yi tanıyan bir tarayıcıda report-to varsa report-uri yoksayılır. Yalnızca report-uri'yı 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-to simgesini report-uri simgesinin yanına ekleyin. Yalnızca report-uri (Firefox) destekleyen tarayıcılar report-uri, report-to(Chrome, Edge) destekleyen tarayıcılar 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 üstbilgilerini kullanın. Bu sayede, 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 tamamı veya çoğu daha sonraki Chrome ya da Edge yüklemelerine (96 ve sonraki sürümler) güncellediğinde Report-To (v0) öğesini kaldırın ve yalnızca Reporting-Endpoints öğesini tutun. report-uri ayarını etkin tutun. Böylece yalnızca bu ayarı destekleyen tarayıcılar için rapor almaya devam edebilirsiniz.

Bu adımlarla ilgili kod örneklerini CSP raporlama taşıma başlıklı makalede bulabilirsiniz.

Taşıma: örnek kod

Genel Bakış

Bir COOP (Cross-Origin-Opener-Policy üstbilgisi), COEP (Cross-Origin-Embedder-Policy) veya doküman politikası (Document-Policy üstbilgisi) için ihlal raporları almak üzere eski Reporting API'yi (v0) kullanıyorsanız Reporting API v1'e geçerken bu politika üstbilgilerinin kendilerini değiştirmeniz gerekmez. Eski Report-To üstbilgisinden yeni Reporting-Endpoints üstbilgisine geçiş yapmanız 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şinizin bir parçası olarak Content-Security-Policy ayarlarınızda değişiklik yapmanız gerekebilir.

Temel taşıma

Eski kod (v0 ile)

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

Yeni kod (v1 ile birlikte v0'ı içeren geçiş kodu)

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" }] }

Sitenizde zaten raporlama işlevi varsa raporları kaybetmemek için Report-To yalnızca geçici olarak (Çoğu Chrome ve Edge istemcisi güncellenene kadar) tutun.

Ağ hatası günlüğüne kaydetme özelliğine ihtiyacınız varsa Report-To ağ hatası günlüğüne kaydetme özelliğinin yerine geçecek bir özellik kullanıma sunulana kadar kullanmaya devam edin.

Yeni kod (yalnızca v1 ile)

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

Çoğu Chrome ve Edge istemcisi güncellenip API v1'i destekledikten sonra kodunuz gelecekte bu şekilde görünebilir.

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özlemleme

Eski kod (v0 ile), örneğin Express ile

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

v0 ile yalnızca bazı yanıtlarda raporlama uç noktaları ayarlayabilirsiniz. Bu kaynakta bulunan diğer belgeler (sayfalar) otomatik olarak bu ortam uç noktalarını kullanır. Burada, "/" için ayarlanan uç noktalar, örneğin page1 için tüm yanıtlarda kullanılır.

Yeni kod (v1 ile), örneğin Express ile

// 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'de, rapor oluşturabilecek tüm yanıtlarda Reporting-Endpoints üstbilgisini ayarlamanız gerekir.

CSP raporlama taşıma işlemi

Yalnızca report-uri içeren eski kod

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

Yalnızca report-uri kullanılması artık önerilmemektedir. Kodunuz yukarıdaki gibi görünüyorsa taşıma işlemini yapın. Aşağıdaki yeni kod örneklerine (yeşil renkte) bakın.

report-uri ve Report-To (v0) başlığıyla report-to yönergesi içeren daha iyi eski kod

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

Bu daha iyidir: Bu kod, report-uri yerine daha yeni bir alternatif olan report-to özelliğini kullanır. Geriye dönük uyumluluk için report-uri'yi korumaya devam eder. Bazı tarayıcılar report-to'ı desteklemez ancak report-uri'ı destekler.

Ancak bu kod, Reporting API v0'ı (Report-To üstbilgisi) kullandığı için daha iyi olabilir. v1'e geçiş: Aşağıdaki "Yeni kod" örneklerine (yeşil renkte) bakın.

Yeni kod, report-uri ve Reporting-Endpoints (v1) üstbilgisiyle report-to yönergesi

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 yönergesi tarayıcılarda desteklenene kadar report-uri yönergesini report-to yönergesiyle birlikte kullanmaya devam edin. Tarayıcı uyumluluğu tablosuna bakın.

Report-To öğesini geçici olarak Reporting-Endpoints ile birlikte tutun. Chrome ve Edge ziyaretçilerinizin çoğu 96 ve üzeri tarayıcı sürümlerine yükselttiğinde Report-To öğesini kaldırın.

Daha fazla bilgi

• Web uygulamanızı Reporting API ile izleme (Reporting API ile ilgili ana gönderi)
• Şartname: eski Reporting API (v0)
• Şartname: yeni Reporting API (v1)

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