Reporting API'nin yeni bir sürümü mevcut. Daha gizlidir ve tarayıcılarda desteklenme olasılığı daha yüksektir.
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.
v0 sürümüyle yalnızca bazı yanıtlarda raporlama uç noktaları ayarlayabilirsiniz. Söz konusu kaynaktaki diğer belgeler (sayfalar) otomatik olarak bu ambiyans uç noktalarını kullanır.
v1 sürümünde, rapor oluşturabilecek tüm yanıtlarda Reporting-Endpoints
üstbilgisini ayarlamanız gerekir.
- 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 birPOST
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
Eski Reporting API (v0)Report-To başlığı |
Yeni Reporting API (v1)Reporting-Endpoints başlığı |
|
---|---|---|
Tarayıcı desteği | Chrome 69 ve sonraki sürümler ile Edge 69 veya sonraki sürümler. | Chrome 96+ ve Edge 96+. Firefox destekler. Safari itiraz etmez. Tarayıcı sinyallerine bakın. |
Uç noktalar | Raporları, birden çok rapor toplayıcısından herhangi birine gönderir (uç nokta grubu başına birden fazla URL tanımlanmış). | Raporları belirli rapor toplayıcılarına 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ış uç noktaları yapılandırmak için `Reporting-Endpoints` üstbilgisini kullanır. |
Bu API aracılığıyla oluşturulabilecek rapor türleri |
|
Network Error Logging (NEL) (Ağ Hatası Günlük Kaydı) dışında değiştirilmez: Bu özellik yeni Reporting API'de (v1) desteklenmez. |
Rapor kapsamı | Kaynağınıza aitmiş gibi ele almasını sağlayan teknoloji. Bir dokümanın Report-To üstbilgisi, söz konusu kaynaktaki diğer dokümanları (sayfaları) etkiler.
Raporların url alanı yine dokümana göre değişir.
|
Doküman. Bir dokümanın Reporting-Endpoints üstbilgisi yalnızca söz konusu dokümanı etkiler.
Raporların url alanı yine dokümana göre değişir.
|
Rapor izolasyonu (toplu işlem) | Yaklaşık olarak aynı zamanda bir rapor oluşturan ve aynı raporlama uç noktasına sahip farklı dokümanlar (sayfalar) veya siteler/kaynaklar birlikte toplu olarak işlenir: Raporlama uç noktasına aynı ileti içinde gönderilirler. |
|
Yük dengeleme / öncelikler için destek | Evet | Hayır |
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 gerekiyorsaReport-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 varsaReport-To
(v0) veReporting-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. Adım (şimdi yapın): İki başlığı da kullanın:
Report-To
(v0) veReporting-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ı örnekleriReporting-Endpoints
kullanır. Bunu desteklemeyen örnekler iseReport-To
kullanır. İstek ve rapor biçimi, v0 ve v1 için aynıdır.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. 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ızcaReporting-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. Raporlarapplication/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 yenisiReporting-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. Adım (şimdi yapın): Henüz eklemediyseniz
report-uri
ile birliktereport-to
ekleyin. Yalnızcareport-uri
(Firefox) desteği olan tarayıcılarreport-uri
protokolünü,report-to
(Chrome, Edge) destekleyen tarayıcılar dareport-to
biçimini kullanır.report-to
içinde kullanacağınız adlandırılmış uç noktaları belirtmek için hemReport-To
hem deReporting-Endpoints
başlıklarını kullanın. Böylece hem eski hem de yeni Chrome ve Edge istemcilerinden rapor alabilirsiniz.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ızcaReporting-Endpoints
kullanın. Yalnızca destekleyen tarayıcılarla ilgili raporları almaya devam etmek içinreport-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.