Bu sayfa, Cloud Translation API ile çevrilmiştir.

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ı

Dikkat: Ağ Hata Günlüğü'nü kullanıyorsanız Reporting API v1'de desteklenmediği için Report-To (v0) kullanmaya devam edin.

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.

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 de 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 sürümünde olduğu 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)

0 sürümü ile yalnızca bazı yanıtlarda raporlama uç noktaları ayarlayabilirsiniz. Bu kaynaktaki diğer belgeler (sayfalar) bu ortam uç noktalarını otomatik olarak kullanır.

v1 (yeni)

1. sürümde, rapor oluşturabilecek tüm yanıtlarda Reporting-Endpoints üstbilgisini ayarlamanız gerekir.

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

	Eski Reporting API (v0) `Report-To` üstbilgisi	Yeni Reporting API (v1) `Reporting-Endpoints` başlığı
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 buna itiraz etmez. Tarayıcı sinyalleri başlıklı makaleyi inceleyin.
Uç noktalar	Raporları birden fazla rapor toplayıcıya (uç nokta grubu başına tanımlanan birden fazla URL) 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ış uç noktaları yapılandırmak için `Reporting-Endpoints` üstbilgisini kullanır.
Bu API aracılığıyla oluşturulabilecek rapor türleri	Kullanımdan Kaldırma Müdahale Kaza COOP/COEP Content-Security-Policy 3. Seviye (CSP 3. Seviye) Ağ Hatası Günlük Kaydı (NEL) _{Rapor türleri hakkında daha fazla bilgi edinmek için Reporting API yayınını inceleyin.}	Network Error Logging (NEL): bu özellik yeni Reporting API'de (v1) desteklenmez hariç olmak üzere değişiklik yapılmamıştır.
Rapor kapsamı	Kaynağınıza aitmiş gibi ele almasını sağlayan teknoloji. Bir dokümanın `Report-To` üstbilgisi, ilgili kaynaktaki diğer dokümanları (sayfaları) etkiler. Raporun `url` alanı, belgeye göre değişmeye devam eder.	Belge. Bir dokümanın `Reporting-Endpoints` üst bilgisi yalnızca o dokümanı etkiler. Raporun `url` alanı, belgeye göre değişmeye devam eder.
Rapor izolasyonu (toplu işleme)	Yaklaşık olarak aynı zamanda rapor oluşturan ve aynı raporlama uç noktasına sahip farklı dokümanlar (sayfalar) veya siteler/kaynaklar birlikte gruplandırılır: Raporlama uç noktasına aynı mesajla gönderilirler.	Farklı dokümanlardan (sayfalardan) alınan raporlar hiçbir zaman birlikte gönderilmez. Aynı kaynaktan iki doküman (sayfa) aynı anda aynı uç nokta için rapor oluştursa bile bunlar toplu olarak işlenmez. Bu, gizlilik saldırılarını azaltmaya yönelik bir mekanizmadır. Aynı dokümandan (sayfadan) alınan raporlar birlikte gönderilebilir.
Yük dengeleme / öncellikler 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ı 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. 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. 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. 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. 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.
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

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'un kullanıldığı 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 raporlama işlevi zaten varsa raporları kaybetmemek için Report-To yalnızca geçici olarak (çoğu Chrome ve Edge istemcisi güncellenene kadar) etkin durumda bırakın.

Ağ Hatası Günlüklerinin kullanılmasına ihtiyacınız varsa Ağ Hatası Günlüklerinin yerini alacak çözüm kullanıma girene kadar Report-To seçeneğini etkin tutun.

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.

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

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(...)
});

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

Express ile yeni kod (v1 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(...)
});

1. sürümde, rapor oluşturabilecek tüm yanıtlarda Reporting-Endpoints başlığını ayarlamanız gerekir.

CSP raporlama taşıma

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 önerilmez. Kodunuz yukarıdaki gibi görünüyorsa taşıma işlemini gerçekleştirin. Aşağıdaki yeni kod örneklerine (yeşil renkli) 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 iyi: Bu kodda, report-uri için daha yeni bir alternatif olan report-to kullanılıyor. Geriye dönük uyumluluk için report-uri özelliğini kullanmaya devam eder. Bazı tarayıcılar report-to özelliğini desteklemez ancak report-uri özelliğini destekler.

Yine de bu daha iyi olabilir: Bu kodlar Reporting API v0'u (Report-To üstbilgisi) kullanır. 1. sürüme taşıma: Aşağıdaki "Yeni kod" örneklerine (yeşil renkli) bakın.

Reporting-Endpoints (v1) başlığıyla birlikte report-uri ve report-to yönergesi içeren yeni kod

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önü tüm tarayıcılarda desteklenene kadar report-uri yönergesini report-to yönergesiyle birlikte kullanın. Tarayıcı uyumluluğu tablosuna bakın.

Report-To'ü geçici olarak Reporting-Endpoints ile birlikte tutun. Chrome ve Edge ziyaretçilerinizin çoğu 96 ve sonraki sürümlere geçtiğinde Report-To öğesini kaldırın.

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.