Reporting API v1'e geçin

Reporting API'nin yeni bir sürümü mevcut. Daha gizlidir ve tarayıcılar arasında desteklenme olasılığı daha yüksektir.

Maud Nalpas

Reporting API, ziyaretçiler sitenizi kullanırken sitenizde gerçekleşen hatalar hakkında sizi bilgilendirir. Bu sayede tarayıcı müdahaleleri, tarayıcı kilitlenmeleri, İçerik-Güvenliği-Politika ihlalleri ve COOP/COEP ihlalleri, desteği sonlandırma uyarıları ve daha fazlası.

Reporting API'nin yeni bir sürümü mevcut. Yeni API daha yalındır ve muhtemelen tarayıcılarda desteklenir.

Özet

Site geliştiriciler

Siteniz için raporlama işlevine zaten sahipseniz: Yeni üst bilgiyi kullanarak v1'e geçin (Reporting-Endpoints) ancak eski başlığı bir süre daha saklayın (Report-To). Taşıma: örnek kod bölümünü inceleyin.

Sitenize şu anda raporlama işlevi ekliyorsanız: Yalnızca yeni başlığı kullanın (Reporting-Endpoints).

⚠️ Her iki durumda da, bunu etkileyebilecek tüm yanıtlarda Reporting-Endpoints başlığını ayarladığınızdan emin olun raporları oluşturun.

Raporlama hizmeti geliştiricileri

Bir uç nokta hizmeti sağlıyor veya kendiniz çalıştırıyorsanız daha fazla trafik bekleyebilirsiniz. veya harici geliştiriciler Reporting API v1'e (Reporting-Endpoints başlığı) geçiş yapar.

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

Demo ve kod

• Demo site: yeni Reporting API (v1)
• Demo site 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.

• 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 desteklenmez. v1'in desteklenme olasılığı daha yüksektir ileride birden fazla tarayıcıda.

Neler değişmedi?

• Raporların biçimi ve yapısı değiştirilmemiştir.
• Tarayıcı tarafından uç noktaya gönderilen istek, Content-type tutarındaki POST isteği olarak kalır 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 herhangi bir etkisi yoktur. ReportingObserver, tüm gözlemlenebilir raporlara erişmeye devam ediyor. Bu raporların biçimi: aynı olmalı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 bir uç nokta için daha fazla trafik bekleyebilirsiniz.

Bunun nedeni, raporların Reporting API v0'da olduğu gibi Reporting API v1 ile toplu olarak gruplandırılmamasıdır. Dolayısıyla, Uygulama geliştiriciler Reporting API v1'e geçiş yaptıkça rapor sayısı Benzer kalır ancak uç nokta sunucusuna yapılan isteklerin hacmi artar.

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 da v1 için (yalnızca Chrome ve Chrome'da desteklenen v0 sürümünden farklı olarak) Kenar).
• API daha yalındır.
• Araçlar, yeni Reporting API (v1) etrafında geliştiriliyor.

Bunu göz önünde bulundurarak:

• Sitenizde Report-To başlığıyla birlikte Reporting API v0 kullanılıyorsa Reporting API v1 (taşıma adımlarına göz atın). Sitenizde zaten İçerik Güvenliği Politikası ihlallerini bildirme işlevi yerine İGP raporlaması için taşıma adımlarını inceleyin.
• Sitenizde Raporlama API'si kullanılmıyorsa ve şimdi raporlama işlevi ekliyorsanız: yeni Reporting API'yi (v1) (Reporting-Endpoints başlığı) kullanmalıdır. Çünkü Çevik felsefesi için şunu kullanın: 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ük Kaydı için yeni bir mekanizma, kullanıma sunulana kadar Reporting API v0'ı kullanın. Ağ Hatası Günlük Kaydına ihtiyacınız varsa Diğer rapor türlerinin yanında Report-To (v0) ve Reporting-Endpoints (v1) ikisini de kullanın. v0 Network Error Logging, v1 ise diğer tüm türlerin raporlarını sunar.

Taşıma adımları

Bu taşımadaki hedefiniz, v0 ile aldığınız raporları kaybetmemek.

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 ve örnek olarak Report-To değerine yedeklenmez. İstek ve rapor biçimi, v0 ve v1.

2. 2. Adım (şimdi yapın): Reporting-Endpoints üstbilgisinin rapor oluşturabilir.

   v0 ile yalnızca bazı yanıtlarda ve diğer dokümanlarda raporlama uç noktaları ayarlamayı seçebilirsiniz. (sayfalar) bu "ambiyans"ı kullanır uç nokta. v1 ile birlikte kullanıldığında, oluşturabilirsiniz. Bu nedenle, gerçekleşebilecek tüm yanıtlarda Reporting-Endpoints başlığını raporlar.

3. 3. Adım (daha sonra başlatın): Kullanıcılarınızın tümü veya çoğu daha sonra Chrome veya Edge'e güncellendikten sonra yüklemeleri (96 ve sonrası), Report-To (v0) kaldırın ve yalnızca Reporting-Endpoints değerini tutun.

   Bir istisna: Ağ Hatası Günlük Kaydı raporlarına ihtiyacınız varsa yeni birReport-To Ağ Hatası Günlüğü için mekanizmanın uygulanmakta olduğunu gösterir.

Taşıma kılavuzundaki kod örneklerini inceleyin.

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

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

• report-uri yönergesi aracılığıyla yalnızca CSP başlığıyla. Bu özellik, Chrome, Firefox, Safari ve Edge. Raporlar, application/csp-report içerik türüyle gönderilir özel bir formatta olması gerekir. Bu raporlara "İGP Düzey 2 Raporları" adı verilir. ve Reporting API'ye bağımsız olmamalıdır.
• Reporting API ile Report-To başlığı (eski) veya daha yeni Reporting-Endpoints (sürüm 1). Bu özellik yalnızca Chrome ve Edge'de desteklenir. Rapor isteklerinde diğer Reporting API istekleriyle aynı biçimde ve aynı içerik türü (application/reports+json) olmalıdır.

İlk yaklaşımı (yalnızca report-uri) kullanmanız artık önerilmez. İkinci yaklaşımın ise birkaç avantajı vardır. Özellikle, tüm rapor türleri için raporlamayı ayarlamak üzere tek bir yöntemden yararlanmanın yanı sıra genel bir uç nokta ayarlamanıza olanak tanır. Bunun nedeni, Reporting API⏤CSP ve diğer tüm rapor istekleri aynı biçimde application/reports+json olacaktır.

Ancak report-to özelliğini yalnızca birkaç tarayıcı destekler. Bu nedenle, Reporting API yaklaşımıyla (Report-To) birlikte report-uri değerini de kullanmanız önerilir. veya daha iyisi Reporting-Endpoints) kullanarak birden çok tarayıcıdan İGP ihlal raporları alabilirsiniz. report-uri ve report-to özelliklerini tanıyan tarayıcı, report-to ise report-uri yoksayılır olduğundan emin olun. Yalnızca report-uri adlı kullanıcıyı tanıyan bir tarayıcıda sadece 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'yi (Firefox) destekleyen tarayıcılar report-uri kullanır ve aynı zamanda desteği report-to(Chrome, Edge) report-to kullanacak. Kullanacağınız adlandırılmış uç noktaları belirtmek için report-to içinde hem Report-To hem de Reporting-Endpoints başlığını kullanın. Bu sayede hem eski hem de yeni Chrome ve Edge istemcilerinden gelen raporları görebilirsiniz.

2. 3. Adım (daha sonra başlatın): Kullanıcılarınızın tümü veya çoğu daha sonra Chrome veya Edge'e güncellendikten sonra yüklemeleri (96 ve sonrası), Report-To (v0) kaldırın ve yalnızca Reporting-Endpoints değerini tutun. Sakla report-uri. Böylece yalnızca bu uzantıyı destekleyen tarayıcılar hakkında raporlar almaya devam edersiniz.

Bu adımlarla ilgili kod örneklerini İGP raporlamasının taşınması bölümünde bulabilirsiniz.

Taşıma: Örnek kod

Genel Bakış

COOP için ihlal raporları almak üzere eski Reporting API'yi (v0) kullanıyorsanız (Cross-Origin-Opener-Policy başlığı), bir COEP (Cross-Origin-Embedder-Policy) veya belge politikası (Document-Policy başlığı): Taşıma sırasında bu politika başlıklarını değiştirmeniz gerekmez Reporting API v1'e geri yükleyin. Yapmanız gereken, eski Report-To başlığından yeni Reporting-Endpoints üstbilgisi.

İGP için ihlal raporları almak üzere eski Reporting API'yi (v0) kullanıyorsanız (Content-Security-Policy üstbilgisi), şunun bir parçası olarak Content-Security-Policy üzerinde değişiklik yapmanız gerekebilir: yeni Reporting API'ye (v1) geçişiniz.

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 siz uç nokta başına yalnızca bir URL'ye sahip 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 raporlarını 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

• Web uygulamanızı Reporting API ile izleme (Reporting API'deki ana yayın)
• Spesifikasyon: eski Reporting API (v0)
• Spesifikasyon: yeni Reporting API (v1)

Nine Koepfer / @enka80'in hero resmi Unsplash, düzenlendi. Ian'ın sayesinde Clelland, Eiji Kitamura ve Milica Mihajlija bu konuyla ilgili incelemeleri ve önerileri için bulabilirsiniz.