Reporting API ile web uygulamanızı izleme

Güvenlik ihlallerini, kullanımdan kaldırılan API çağrılarını ve daha fazlasını izlemek için Reporting API'yi kullanın.

Maud Nalpas

Bazı hatalar yalnızca üretimde oluşur. Gerçek kullanıcılar, gerçek ağlar ve gerçek cihazlar işleri değiştirdiği için bunları yerel olarak veya geliştirme sırasında görmezsiniz. Reporting API, bu hatalardan bazılarını (ör. sitenizdeki güvenlik ihlalleri veya kullanımdan kaldırılan ve yakında kullanımdan kaldırılacak API çağrıları) yakalamanıza yardımcı olur ve bunları belirttiğiniz bir uç noktaya iletir.

HTTP üstbilgilerini kullanarak izlemek istediklerinizi bildirmenize olanak tanır ve tarayıcı tarafından çalıştırılır.

Reporting API'yi ayarladığınızda, kullanıcılar bu tür hatalarla karşılaştığında haberdar olacağınızdan ve bu hataları düzeltebileceğinizden emin olabilirsiniz.

Bu yayında, bu API'nin neler yapabileceği ve nasıl kullanılacağı açıklanmaktadır. Haydi başlayalım.

Genel Bakış

Aşağıdaki adımları (rapor oluşturmadan geliştiricinin rapora erişimine kadar) özetleyen şema — Raporlar nasıl oluşturulur ve gönderilir?

site.example adlı sitenizin bir Content-Security-Policy ve bir Document-Policy'ye sahip olduğunu varsayalım. Bu ayarların ne işe yaradığını bilmiyor musunuz? Bu örnekten yine de yararlanabilirsiniz.

Bu politikaların ne zaman ihlal edildiğini öğrenmek için sitenizi izlemeye karar verirsiniz. Bununla birlikte, kod tabanınızın kullanıyor olabileceği, desteği sonlandırılmış veya yakında desteği sonlandırılacak API'leri de takip etmek istersiniz.

Bunu yapmak için bir Reporting-Endpoints üstbilgisi yapılandırır ve bu uç nokta adlarını, politikalarınızda gerektiğinde report-to yönergesini kullanarak eşlersiniz.

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

# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0; report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the `default` endpoint

Beklenmedik bir durum yaşanır ve bu politikalar bazı kullanıcılarınız için ihlal edilir.

İhlal örnekleri

index.html

<script src="script.js"></script>
<!-- CSP VIOLATION: Try to load a script that's forbidden as per the Content-Security-Policy -->
<script src="https://example.com/script.js"></script>

script.js, index.html tarafından yüklendi

// DOCUMENT-POLICY VIOLATION: Attempt to use document.write despite the document policy
try {
  document.write('<h1>hi</h1>');
} catch (e) {
  console.log(e);
}
// DEPRECATION: Call a deprecated API
const webkitStorageInfo = window.webkitStorageInfo;

Tarayıcı, bu sorunları yakalayan bir CSP ihlali raporu, bir Document-Policy ihlali raporu ve bir Kullanımdan Kaldırma raporu oluşturur.

Tarayıcı, bir dakikaya kadar sürebilen kısa bir gecikmeyle raporları bu ihlal türü için yapılandırılmış uç noktaya gönderir. Raporlar, tarayıcının kendisi tarafından bant dışı olarak gönderilir (sunucunuz veya siteniz tarafından değil).

Uç noktalar bu raporları alır.

Artık bu uç noktalardaki raporlara erişebilir ve neyin yanlış gittiğini izleyebilirsiniz. Kullanıcılarınızı etkileyen sorunu gidermeye başlayabilirsiniz.

Örnek rapor

{
  "age": 2,
  "body": {
    "blockedURL": "https://site2.example/script.js",
    "disposition": "enforce",
    "documentURL": "https://site.example",
    "effectiveDirective": "script-src-elem",
    "originalPolicy": "script-src 'self'; object-src 'none'; report-to main-endpoint;",
    "referrer": "https://site.example",
    "sample": "",
    "statusCode": 200
  },
  "type": "csp-violation",
  "url": "https://site.example",
  "user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
}

Kullanım alanları ve rapor türleri

Reporting API, sitenizde gerçekleşen birçok ilginç uyarı veya sorunu izlemenize yardımcı olacak şekilde yapılandırılabilir:

Rapor türü	Rapor oluşturulacak bir durum örneği
İGP ihlali (yalnızca 3. düzey)	Sayfalarınızdan birinde `Content-Security-Policy` (CSP) ayarladınız ancak sayfa, CSP'niz tarafından izin verilmeyen bir komut dosyası yüklemeye çalışıyor.
COOP ihlali	Bir sayfada `Cross-Origin-Opener-Policy` ayarladınız ancak çapraz kaynaklı bir pencere doğrudan dokümanla etkileşime girmeye çalışıyor.
COEP ihlali	Bir sayfada `Cross-Origin-Embedder-Policy` ayarladınız ancak dokümanda, kaynaklar arası dokümanlar tarafından yüklenmeyi etkinleştirmemiş bir kaynaklar arası iframe var.
Belge Politikası ihlali	Sayfada, `document.write` kullanımını engelleyen bir doküman politikası var ancak bir komut dosyası `document.write`'yı çağırmaya çalışıyor.
İzin politikası ihlali	Sayfada, mikrofon kullanımını engelleyen bir izin politikası ve ses girişi isteyen bir komut dosyası var.
Kullanımdan kaldırma uyarısı	Sayfa, desteği sonlandırılmış veya sonlandırılacak bir API kullanıyor. Bu API'yi doğrudan ya da üst düzey bir üçüncü taraf komut dosyası kullanarak çağırıyor.
Müdahale	Sayfa, tarayıcının güvenlik, performans veya kullanıcı deneyimi nedenleriyle kabul etmemeye karar verdiği bir işlem yapmaya çalışıyor. Chrome'daki örnek: Sayfa, `document.write` işlevini yavaş ağlarda kullanıyor veya kullanıcının henüz etkileşimde bulunmadığı bir kaynaklar arası çerçevede `navigator.vibrate` işlevini çağırıyor.
Kaza	Tarayıcı, siteniz açıkken çöker.

Raporlar

Raporlar nasıl görünür?

Tarayıcı, yapılandırdığınız uç noktaya rapor gönderir. Aşağıdaki gibi görünen istekler gönderir:

POST
Content-Type: application/reports+json

Bu isteklerin yükü, rapor listesidir.

Örnek rapor listesi

[
  {
    "age": 420,
    "body": {
      "columnNumber": 12,
      "disposition": "enforce",
      "lineNumber": 11,
      "message": "Document policy violation: document-write is not allowed in this document.",
      "policyId": "document-write",
      "sourceFile": "https://site.example/script.js"
    },
    "type": "document-policy-violation",
    "url": "https://site.example/",
    "user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
  },
  {
    "age": 510,
    "body": {
      "blockedURL": "https://site.example/img.jpg",
      "destination": "image",
      "disposition": "enforce",
      "type": "corp"
    },
    "type": "coep",
    "url": "https://dummy.example/",
    "user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
  }
]

Bu raporların her birinde bulabileceğiniz veriler şunlardır:

Alan	Açıklama
`age`	Raporun zaman damgası ile geçerli saat arasındaki milisaniye sayısı.
`body`	Gerçek rapor verileri, JSON dizesi olarak serileştirilir. Bir raporun `body` bölümünde yer alan alanlar, raporun `type` bölümüne göre belirlenir. ⚠️ Farklı türlerdeki raporların gövdeleri farklıdır.
`type`	Rapor türü (örneğin, `csp-violation` veya `coep`).
`url`	Raporun oluşturulduğu dokümanın veya çalışanın adresi. Kullanıcı adı, şifre ve parça gibi hassas veriler bu URL'den kaldırılır.
`user_agent`	Raporun oluşturulduğu istekten gelen `User-Agent` üstbilgisi.

Kimlik bilgisi içeren raporlar

Raporu oluşturan sayfayla aynı kaynağa sahip raporlama uç noktaları, raporları içeren isteklerde kimlik bilgilerini (çerezler) alır.

Kimlik bilgileri, rapor hakkında faydalı ek bağlam sağlayabilir. Örneğin, belirli bir kullanıcının hesabının sürekli olarak hatalara neden olup olmadığı veya diğer sayfalarda gerçekleştirilen belirli bir işlem sırasının bu sayfada bir raporu tetikleyip tetiklemediği gibi.

Tarayıcı ne zaman ve nasıl rapor gönderir?

Raporlar, sitenizden bant dışı olarak gönderilir: Tarayıcı, yapılandırılmış uç noktalara ne zaman gönderileceğini kontrol eder. Tarayıcının raporları ne zaman göndereceğini kontrol etmenin de bir yolu yoktur. Tarayıcı, raporları uygun bir zamanda otomatik olarak yakalar, sıraya alır ve gönderir.

Bu nedenle, Reporting API'yi kullanırken performansla ilgili endişelenmenize gerek yoktur.

Raporlar, toplu olarak gönderilme olasılığını artırmak için bir dakikaya kadar gecikmeli olarak gönderilir. Bu sayede, kullanıcının ağ bağlantısına saygı göstermek için bant genişliği tasarrufu sağlanır. Bu durum özellikle mobil cihazlarda önemlidir. Tarayıcı, daha yüksek öncelikli işleri işlemekle meşgulse veya kullanıcı o sırada yavaş ya da yoğun bir ağ kullanıyorsa teslimatı da geciktirebilir.

Üçüncü taraf ve birinci taraf sorunları

Sayfanızda meydana gelen ihlaller veya desteği sonlandırılan özellikler nedeniyle oluşturulan raporlar, yapılandırdığınız uç noktalara gönderilir. Buna, sayfanızda çalışan üçüncü taraf komut dosyaları tarafından işlenen ihlaller de dahildir.

Sayfanıza yerleştirilmiş bir kaynaklar arası iFrame'de meydana gelen ihlaller veya desteği sonlandırılan özellikler, uç noktalarınıza bildirilmez (en azından varsayılan olarak). Bir iFrame kendi raporlamasını ayarlayabilir ve hatta sitenizin (yani birinci tarafın) raporlama hizmetine rapor gönderebilir. Ancak bu, çerçeveli siteye bağlıdır. Ayrıca, çoğu raporun yalnızca bir sayfanın politikası ihlal edildiğinde oluşturulduğunu ve sayfanızın politikaları ile iFrame'in politikalarının farklı olduğunu unutmayın.

Kullanımdan kaldırılan özellikler içeren örnek

Sayfanızda Reporting-Endpoints üstbilgisi ayarlanmışsa: Sayfanızda çalışan üçüncü taraf komut dosyaları tarafından çağrılan, desteği sonlandırılmış API, uç noktanıza bildirilir. Sayfanıza yerleştirilmiş bir iFrame tarafından çağrılan, desteği sonlandırılmış API, uç noktanıza bildirilmez. Kullanımdan kaldırma raporu yalnızca iFrame sunucusu Reporting-Endpoints'i ayarladıysa oluşturulur ve bu rapor, iFrame'in sunucusunun ayarladığı uç noktaya gönderilir. — Sayfanızda Reporting-Endpoints üstbilgisi ayarlanmışsa: Sayfanızda çalışan üçüncü taraf komut dosyaları tarafından çağrılan, desteği sonlandırılmış API'ler uç noktanıza bildirilir. Sayfanıza yerleştirilmiş bir iFrame tarafından çağrılan, desteği sonlandırılmış API, uç noktanıza bildirilmez. Kullanımdan kaldırma raporu yalnızca iFrame sunucusu Reporting-Endpoints'i ayarladıysa oluşturulur ve bu rapor, iFrame'in sunucusunun ayarladığı uç noktaya gönderilir.

Tarayıcı desteği

Aşağıdaki tabloda, Reporting-Endpoints üstbilgisine sahip Reporting API v1'in tarayıcı desteği özetlenmektedir. Reporting API v0 (Report-To üstbilgisi) için tarayıcı desteği, bir rapor türü hariç aynıdır: Ağ Hatası Günlüğü, yeni Reporting API'de desteklenmez. Ayrıntılar için taşıma rehberini inceleyin.

Rapor türü	Chrome	Chrome iOS	Safari	Firefox	Edge
İGP ihlali (yalnızca 3. düzey)*	✔ Evet	✔ Evet	✔ Evet	✘ Hayır	✔ Evet
Ağ Hatası Günlüğü	✘ Hayır	✘ Hayır	✘ Hayır	✘ Hayır	✘ Hayır
COOP/COEP ihlali	✔ Evet	✘ Hayır	✔ Evet	✘ Hayır	✔ Evet
Diğer tüm türler: Belge Politikası ihlali, Kullanımdan Kaldırma, Müdahale, Kilitlenme	✔ Evet	✘ Hayır	✘ Hayır	✘ Hayır	✔ Evet

Bu tabloda yalnızca yeni Reporting-Endpoints başlığıyla report-to desteği özetlenmektedir. Reporting-Endpoints'e geçiş yapmak istiyorsanız CSP raporlama taşıma ipuçlarını okuyun.

Raporlama API'sini kullanma

Raporların nereye gönderileceğine karar verme

Bunun için iki seçeneğiniz bulunmaktadır:

Raporları mevcut bir rapor toplayıcı hizmetine gönderme
Raporları, kendinizin oluşturup işlettiği bir raporlama toplayıcısına gönderme

1. seçenek: Mevcut bir rapor toplayıcı hizmetini kullanma

Rapor toplayıcı hizmetlere bazı örnekler:

Başka çözümler biliyorsanız sorun kaydı açarak bize bildirin. Bu gönderiyi güncelleyelim.

Rapor toplayıcı seçerken fiyatlandırmanın yanı sıra aşağıdaki noktaları da göz önünde bulundurun: 🧐

Bu toplayıcı tüm rapor türlerini destekliyor mu? Örneğin, tüm raporlama uç nokta çözümleri COOP/COEP raporlarını desteklemez.
Uygulamanızın URL'lerinden herhangi birini üçüncü taraf rapor toplayıcıyla paylaşma konusunda rahat mısınız? Tarayıcı bu URL'lerden hassas bilgileri kaldırmış olsa bile hassas bilgiler bu şekilde sızabilir. Bu durum uygulamanız için çok riskli görünüyorsa kendi raporlama uç noktanızı çalıştırın.

2. seçenek: Kendi rapor toplayıcınızı oluşturun ve çalıştırın

Raporları alan kendi sunucunuzu oluşturmak o kadar da kolay değildir. Başlamak için basit şablonumuzu çatallayabilirsiniz. Express ile oluşturulmuştur ve raporları alıp görüntüleyebilir.

Kendi rapor toplayıcınızı oluşturduğunuzda:

Tarayıcı tarafından uç noktanıza gönderilen rapor isteklerini tanımak için POST Content-Type application/reports+json isteklerini kontrol edin.
Uç noktanız sitenizden farklı bir kaynakta bulunuyorsa CORS ön kontrolü isteklerini desteklediğinden emin olun.

3. seçenek: 1. ve 2. seçeneği birleştirme

Bazı rapor türleriyle belirli bir sağlayıcının ilgilenmesini, diğerleriyle ise şirket içi bir çözümün ilgilenmesini isteyebilirsiniz.

Bu durumda, birden fazla uç noktayı aşağıdaki gibi ayarlayın:

Reporting-Endpoints: endpoint-1="https://reports-collector.example", endpoint-2="https://my-custom-endpoint.example"

`Reporting-Endpoints` başlığını yapılandırma

Reporting-Endpoints yanıt başlığı ayarlayın. Değeri, virgülle ayrılmış bir veya bir dizi anahtar/değer çifti olmalıdır:

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

Eski Reporting API'den yeni Reporting API'ye geçiş yapıyorsanız Reporting-Endpoints ve Report-To her ikisini de ayarlamanız mantıklı olabilir. Ayrıntılar için taşıma rehberine bakın. Özellikle de yalnızca Content-Security-Policyreport-uri yönergesini kullanarak ihlallerle ilgili raporlama yapıyorsanız CSP raporlamasıyla ilgili taşıma adımlarını inceleyin.

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

Anahtarlar (uç nokta adları)

Her anahtar, main-endpoint veya endpoint-1 gibi istediğiniz bir ad olabilir. Farklı rapor türleri için farklı adlandırılmış uç noktalar ayarlayabilirsiniz. Örneğin, my-coop-endpoint, my-csp-endpoint. Bu sayede, raporları türlerine bağlı olarak farklı uç noktalara yönlendirebilirsiniz.

Müdahale, kullanımdan kaldırma, kilitlenme raporları veya bunların bir kombinasyonunu almak istiyorsanız default adlı bir uç nokta ayarlayın.

Reporting-Endpoints başlığı default uç noktası tanımlamıyorsa bu türdeki raporlar oluşturulmalarına rağmen gönderilmez.

Önemli nokta: Adına rağmen default, yedek uç nokta değildir. Örneğin, report-to my-endpoint için Document-Policy'yi ayarlayıp Reporting-Endpoints içinde my-endpoint'yi tanımlamayı unutursanız Document-Policy ihlalleri raporları oluşturulur ancak tarayıcı, raporları nereye göndereceğini bilmediği için gönderilmez.

Değerler (URL'ler)

Her değer, raporların gönderileceği, sizin seçtiğiniz bir URL'dir. Burada ayarlanacak URL, 1. adımda neye karar verdiğinize bağlıdır.

Bir uç nokta URL'si:

Eğik çizgiyle (/) başlamalıdır. Göreli yollar desteklenmez.
Kaynaklar arası olabilir ancak bu durumda raporlarla birlikte kimlik bilgileri gönderilmez.

Örnekler

Reporting-Endpoints: my-coop-endpoint="https://reports.example/coop", my-csp-endpoint="https://reports.example/csp", default="https://reports.example/default"

Daha sonra, her bir adlandırılmış uç noktayı uygun politikada veya tüm politikalarda tek bir uç nokta olarak kullanabilirsiniz.

Başlık nerede ayarlanır?

Bu yayında ele alınan yeni Reporting API'de raporlar belgeler ile sınırlandırılır. Bu, belirli bir kaynak için site.example/page1 ve site.example/page2 gibi farklı dokümanların farklı uç noktalara rapor gönderebileceği anlamına gelir.

Sitenizin herhangi bir sayfasında gerçekleşen ihlaller veya desteği sonlandırılan özellikler için rapor almak istiyorsanız üst bilgiyi tüm yanıtlarda ara yazılım olarak ayarlayın.

Express'teki bir örneği aşağıda bulabilirsiniz:

const REPORTING_ENDPOINT_BASE = 'https://report.example';
const REPORTING_ENDPOINT_MAIN = `${REPORTING_ENDPOINT_BASE}/main`;
const REPORTING_ENDPOINT_DEFAULT = `${REPORTING_ENDPOINT_BASE}/default`;

app.use(function (request, response, next) {
  // Set up the Reporting API
  response.set(
    'Reporting-Endpoints',
    `main-endpoint="${REPORTING_ENDPOINT_MAIN}", default="${REPORTING_ENDPOINT_DEFAULT}"`,
  );
  next();
});

Not: Bu, bir sayfa için "ortam" uç noktası ayarlayabildiğiniz ve aynı kaynakta bulunan tüm sayfalar için otomatik olarak rapor alabildiğiniz eski Reporting API'den (Report-To üstbilgisi) farklıdır. Eski Reporting API'den yeni Reporting API'ye geçiş yapıyorsanız taşıma rehberini inceleyin.

Politikalarınızı düzenleme

Reporting-Endpoints üstbilgisi yapılandırıldığına göre, ihlal raporları almak istediğiniz her politika üstbilgisine bir report-to yönergesi ekleyin. report-to değeri, yapılandırdığınız adlandırılmış uç noktalardan biri olmalıdır.

Birden fazla politika için çoklu uç nokta kullanabilir veya politikalar arasında farklı uç noktalar kullanabilirsiniz.

Her politika için report-to değeri, yapılandırdığınız adlandırılmış uç noktalardan biri olmalıdır.

Desteğin sonlandırılması, müdahale ve kilitlenme raporları için report-to gerekmez. Bu raporlar herhangi bir politikaya bağlı değildir. default uç noktası ayarlandığı sürece oluşturulur ve bu default uç noktasına gönderilir.

Örnek

# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0;report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the default endpoint

Uyarı: Tüm politikalarda aynı başlık yapısı kullanılmadığından report-to söz dizimini doğru şekilde kullanmak zor olabilir. Politikaya bağlı olarak doğru söz dizimi report-to=main-endpoint veya report-to main-endpoint olabilir.

Raporlama ayarlarınızda hata ayıklama

Kasıtlı olarak rapor oluşturma

Raporlama API'sini ayarlarken raporların beklendiği gibi oluşturulup gönderildiğini kontrol etmek için politikalarınızı kasıtlı olarak ihlal etmeniz gerekebilir.

Zamandan kazanın

Raporlar yaklaşık bir dakika gecikmeyle gönderilebilir. Bu süre, hata ayıklama sırasında uzun bir süredir. 😴 Neyse ki Chrome'da hata ayıklama yaparken raporlar oluşturulur oluşturulmaz almak için --short-reporting-delay işaretini kullanabilirsiniz.

Bu işareti etkinleştirmek için terminalinizde şu komutu çalıştırın:

YOUR_PATH/TO/EXECUTABLE/Chrome --short-reporting-delay

Geliştirici Araçları'nı kullanma

Chrome'da, gönderilmiş veya gönderilecek raporları görmek için Geliştirici Araçları'nı kullanın.

Bu özellik, Ekim 2021 itibarıyla deneyseldir. Bu özelliği kullanmak için aşağıdaki adımları uygulayın:

Chrome'un 96 ve sonraki sürümlerini kullanın (tarayıcınıza chrome://version yazarak kontrol edebilirsiniz).
Chrome'un adres çubuğuna chrome://flags/#enable-experimental-web-platform-features yazın veya yapıştırın.
Etkin'i tıklayın.
Tarayıcınızı yeniden başlatın.
Chrome Geliştirici Araçları'nı açın.
Chrome Geliştirici Araçları'nda Ayarlar'ı açın. Denemeler bölümünde Uygulama panelinde Raporlama API'si panelini etkinleştirin'i tıklayın.
Geliştirici Araçları'nı yeniden yükleyin.
Sayfanızı yeniden yükleyin. Geliştirici Araçları'nın açık olduğu sayfada oluşturulan raporlar, Chrome Geliştirici Araçları'nın Uygulama panelindeki Reporting API altında listelenir.

Raporların listelendiği Geliştirici Araçları'nın ekran görüntüsü — Chrome Geliştirici Araçları, sayfanızda oluşturulan raporları ve durumlarını gösterir.

Rapor durumu

Durum sütununda, raporun başarıyla gönderilip gönderilmediği gösterilir.

Durum	Açıklama
`Success`	Tarayıcı raporu göndermiş ve uç nokta, başarılı sonuç koduyla (`200` veya başka bir başarılı sonuç kodu `2xx`) yanıt vermiştir.
`Pending`	Tarayıcı, raporu göndermeye çalışıyor.
`Queued`	Rapor oluşturulmuş ve tarayıcı raporu göndermeye çalışmıyor. Bir rapor, şu iki durumdan birinde `Queued` olarak görünür: Rapor yenidir ve tarayıcı, göndermeyi denemeden önce başka raporların gelip gelmeyeceğini beklemektedir. Rapor yeni değil. Tarayıcı bu raporu daha önce göndermeyi denedi ve başarısız oldu. Tekrar denemeden önce bekliyor.
`MarkedForRemoval`	Tarayıcı bir süre (`Queued`) yeniden denedikten sonra raporu göndermeyi durdurdu ve kısa süre içinde gönderilecek raporlar listesinden kaldıracak.

Raporlar, başarıyla gönderilip gönderilmediklerine bakılmaksızın bir süre sonra kaldırılır.

Önemli nokta: Queued durumu, gönderimin başarısız olup olmadığını veya henüz denenip denenmediğini tam olarak belirtmediğinden her zaman bilgilendirici değildir. Kısa raporlama gecikmeleri kullanmak şu konularda yardımcı olur: Queued Bu durumda raporun gönderilmemesi, gönderimin başarısız olduğunu gösterir.

Sorun giderme

Raporlar oluşturulmuyor mu veya uç noktanıza beklendiği gibi gönderilmiyor mu? Bu sorunu gidermek için birkaç ipucu aşağıda verilmiştir.

Raporlar oluşturulmuyor

Geliştirici Araçları'nda gösterilen raporlar doğru şekilde oluşturulmuştur. Beklediğiniz rapor bu listede görünmüyorsa:

Politikalarınızda report-to işaretini kontrol edin. Bu ayar yanlış yapılandırılırsa rapor oluşturulmaz. Bu sorunu düzeltmek için Politikalarınızı düzenleme sayfasına gidin. Bu sorunu gidermenin bir başka yolu da Chrome'daki Geliştirici Araçları konsolunu kontrol etmektir: Konsolda beklediğiniz ihlalle ilgili bir hata görünüyorsa politikanız muhtemelen doğru şekilde yapılandırılmıştır.
Bu listede yalnızca DevTools'un açık olduğu doküman için oluşturulan raporların gösterileceğini unutmayın. Örneğin, siteniz site1.example bir politikayı ihlal eden bir iFrame site2.example yerleştiriyorsa ve bu nedenle bir rapor oluşturuluyorsa bu rapor, yalnızca iFrame'i kendi penceresinde açıp bu pencere için DevTools'u açarsanız DevTools'da gösterilir.

Raporlar oluşturuluyor ancak gönderilmiyor veya alınmıyor

DevTools'ta bir rapor görebiliyorsanız ancak uç noktanız bu raporu almıyorsa ne olur?

Önemli nokta: Rapor, belirli bir site tarafından değil, tarayıcının kendisi tarafından bant dışı olarak gönderildiğinden raporları içeren POST istekleri, Geliştirici Araçlarınızın Ağ panelinde gösterilmez.

Kısa gecikmeler kullandığınızdan emin olun. Bir raporu görememenizin nedeni, raporun henüz gönderilmemiş olması olabilir.
Reporting-Endpoints üstbilgi yapılandırmanızı kontrol edin. Bu durumda sorun varsa doğru şekilde oluşturulmuş bir rapor gönderilmez. Bu durumda, DevTools'da raporun durumu Queued olarak kalır (bir teslimat girişimi yapıldığında Pending durumuna geçip ardından hızlıca Queued durumuna geri dönebilir). Bu duruma neden olabilecek yaygın hatalardan bazıları:
Uç nokta kullanılıyor ancak yapılandırılmadı. Örnek:

Hatalı kod

 Document-Policy: document-write=?0;report-to=endpoint-1;
 Reporting-Endpoints: default="https://reports.example/default"

Document-Policy ihlal raporları endpoint-1 adresine gönderilmelidir ancak bu uç nokta adı Reporting-Endpoints içinde yapılandırılmamıştır.

default uç noktası eksik. Kullanımdan kaldırma ve müdahale raporları gibi bazı rapor türleri yalnızca default adlı uç noktaya gönderilir. Daha fazla bilgi için Raporlama uç noktaları üstbilgisini yapılandırma başlıklı makaleyi inceleyin.
Politika başlıklarınızın söz diziminde tırnak işaretlerinin eksik olması gibi sorunları arayın. Ayrıntıları görün.

Uç noktanızın gelen istekleri işleyebildiğinden emin olun.

Uç noktanızın CORS ön kontrol isteklerini desteklediğinden emin olun. Aksi takdirde rapor alamaz.
Uç noktanızın davranışını test edin. Bunu yapmak için raporları manuel olarak oluşturmak yerine, uç noktanıza tarayıcının göndereceği isteklere benzeyen istekler göndererek tarayıcıyı taklit edebilirsiniz. Aşağıdaki komutu çalıştırın:

curl --header "Content-Type: application/reports+json" \
  --request POST \
  --data '[{"age":420,"body":{"columnNumber":12,"disposition":"enforce","lineNumber":11,"message":"Document policy violation: document-write is not allowed in this document.","policyId":"document-write","sourceFile":"https://dummy.example/script.js"},"type":"document-policy-violation","url":"https://dummy.example/","user_agent":"xxx"},{"age":510,"body":{"blockedURL":"https://dummy.example/img.jpg","destination":"image","disposition":"enforce","type":"corp"},"type":"coep","url":"https://dummy.example/","user_agent":"xxx"}]' \
  YOUR_ENDPOINT

Uç noktanız bir başarı koduyla (200 veya başka bir başarı yanıt kodu 2xx) yanıt vermelidir. Aksi takdirde, uç noktanın yapılandırmasında bir sorun vardır.

İlgili bildirme mekanizmaları

Yalnızca Rapor

-Report-Only politika başlıkları ve Reporting-Endpoints birlikte çalışır.

Reporting-Endpoints içinde yapılandırılan ve report-to alanında belirtilen uç noktalar Content-Security-Policy, Cross-Origin-Embedder-Policy ve Cross-Origin-Opener-Policy, bu politikalar ihlal edildiğinde rapor alır.

Reporting-Endpoints içinde yapılandırılan Endpoints, Content-Security-Policy-Report-Only, Cross-Origin-Embedder-Policy-Report-Only ve Cross-Origin-Opener-Policy-Report-Only öğelerinin report-to alanında da belirtilebilir. Bu politikalar ihlal edildiğinde de rapor alırlar.

Her iki durumda da rapor gönderilse de -Report-Only üstbilgileri politikaları zorunlu kılmaz: Hiçbir şey bozulmaz veya gerçekten engellenmez ancak bozulacak ya da engellenecek öğelerle ilgili raporlar alırsınız.

Not: -Report-Only üstbilgisini kullanıyorsanız ve raporlama uç noktalarınızı eski üstbilgi Report-To ile yapılandırdıysanız mümkünse Reporting-Endpoints üstbilgisine geçin. Daha fazla bilgi için taşıma rehberini inceleyin.

`ReportingObserver`

ReportingObserver JavaScript API, istemci tarafı uyarıları gözlemlemenize yardımcı olabilir.

ReportingObserver ve Reporting-Endpoints üstbilgisi aynı görünüme sahip raporlar oluşturur ancak biraz farklı kullanım alanları sağlar.

ReportingObserver uygulamasını şu durumlarda kullanın:

Yalnızca desteği sonlandırılan özellikleri veya tarayıcı müdahalelerini izlemek istiyorsunuz. ReportingObserver, desteği sonlandırılan özellikler ve tarayıcı müdahaleleri gibi istemci tarafı uyarılarını gösterir ancak Reporting-Endpoints'ın aksine CSP veya COOP/COEP ihlalleri gibi başka rapor türlerini yakalamaz.
Bu ihlallere anında tepki vermeniz gerekir. ReportingObserver Geri çağırma işlevinin ihlal etkinliğine eklenmesini sağlar.
Özel geri çağırma işlevini kullanarak hata ayıklamaya yardımcı olmak için bir rapora ek bilgiler eklemek istiyorsunuz.

Bir diğer fark ise ReportingObserver yalnızca istemci tarafında yapılandırılır: Sunucu tarafı üstbilgileri üzerinde kontrolünüz olmasa ve Reporting-Endpoints ayarlayamasanız bile bu özelliği kullanabilirsiniz.

Daha fazla bilgi

Nine Koepfer / @enka80 tarafından Unsplash'te çekilen ve düzenlenen hero resmi. Bu dokümanla ilgili incelemeleri ve önerileri için Ian Clelland, Eiji Kitamura ve Milica Mihajlija'ya çok teşekkür ederiz.