مراقبة تطبيق الويب باستخدام Reporting API

يمكنك استخدام Reporting API لمراقبة انتهاكات الأمان وطلبات البيانات من واجهات برمجة التطبيقات المتوقفة نهائيًا والمزيد.

Maud Nalpas

تحدث بعض الأخطاء في مرحلة الإنتاج فقط. لن تظهر لك هذه المشاكل محليًا أو أثناء التطوير لأنّ المستخدمين الحقيقيين والشبكات الحقيقية والأجهزة الحقيقية تغيّر قواعد اللعبة. تساعد واجهة Reporting API في رصد بعض هذه الأخطاء، مثل انتهاكات الأمان أو طلبات البيانات من واجهة برمجة التطبيقات التي تم إيقافها نهائيًا أو التي سيتم إيقافها نهائيًا قريبًا على مستوى موقعك الإلكتروني، وتنقلها إلى نقطة نهاية حدّدتها.

تتيح لك هذه الواجهة تحديد ما تريد مراقبته باستخدام عناوين HTTP، ويتم تشغيلها من خلال المتصفّح.

يمنحك إعداد Reporting API راحة البال، فعندما يواجه المستخدمون هذه الأنواع من الأخطاء، ستعرف ذلك، حتى تتمكّن من إصلاحها.

تتناول هذه المشاركة ما يمكن أن تفعله واجهة برمجة التطبيقات هذه وكيفية استخدامها. لنطّلع على التفاصيل.

نظرة عامة

لنفترض أنّ موقعك الإلكتروني، site.example، يتضمّن سياسة أمان المحتوى وسياسة مستند. ألا تعرف وظيفة هذه الخيارات؟ لا بأس، سيظل بإمكانك فهم هذا المثال.

لذا، قررت مراقبة موقعك الإلكتروني لمعرفة متى يتم انتهاك هذه السياسات، وأيضًا لأنك تريد مراقبة واجهات برمجة التطبيقات المتوقفة نهائيًا أو التي سيتم إيقافها نهائيًا قريبًا والتي قد تستخدمها قاعدة الرموز البرمجية.

لإجراء ذلك، عليك ضبط عنوان Reporting-Endpoints وربط أسماء نقاط النهاية هذه باستخدام توجيه report-to في سياساتك عند الحاجة.

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

يحدث أمر غير متوقّع، ويتم انتهاك هذه السياسات لبعض المستخدمين.

أمثلة على الانتهاكات

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

// 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;

ينشئ المتصفّح تقريرًا عن انتهاك سياسة أمان المحتوى (CSP) وتقريرًا عن انتهاك سياسة المستندات وتقريرًا عن الإيقاف النهائي يتضمّن هذه المشاكل.

بعد تأخير قصير يصل إلى دقيقة واحدة، يرسل المتصفّح التقارير إلى نقطة النهاية التي تم ضبطها لنوع المخالفة هذا. يتم إرسال التقارير خارج النطاق من خلال المتصفّح نفسه (وليس من خلال الخادم أو الموقع الإلكتروني).

تتلقّى نقاط النهاية هذه التقارير.

يمكنك الآن الوصول إلى التقارير على نقاط النهاية هذه وتتبُّع المشاكل التي حدثت. أنت الآن جاهز لبدء تحديد المشكلة التي تؤثر في المستخدمين وحلّها.

مثال على التقرير

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

حالات الاستخدام وأنواع التقارير

يمكن ضبط Reporting API لمساعدتك في مراقبة العديد من أنواع التحذيرات أو المشاكل المهمة التي تحدث في موقعك الإلكتروني:

التقارير

يرسل المتصفّح التقارير إلى نقطة النهاية التي ضبطتها. ويرسل طلبات تبدو على النحو التالي:

POST
Content-Type: application/reports+json

حمولة هذه الطلبات هي قائمة بالتقارير.

مثال على قائمة التقارير

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

في ما يلي البيانات التي يمكنك العثور عليها في كلّ من هذه التقارير:

التقارير المعتمدة

تتلقّى نقاط نهاية إعداد التقارير التي لها المصدر نفسه مثل الصفحة التي تنشئ التقرير بيانات الاعتماد (ملفات تعريف الارتباط) في الطلبات التي تحتوي على التقارير.

قد توفّر بيانات الاعتماد سياقًا إضافيًا مفيدًا حول البلاغ، مثل ما إذا كان حساب مستخدم معيّن يؤدي إلى حدوث أخطاء باستمرار، أو ما إذا كان هناك تسلسل معيّن من الإجراءات التي تم اتخاذها على صفحات أخرى يؤدي إلى إنشاء بلاغ على هذه الصفحة.

متى وكيف يرسل المتصفّح التقارير؟

يتم إرسال التقارير خارج النطاق من موقعك الإلكتروني: يتحكّم المتصفّح في وقت إرسالها إلى نقاط النهاية التي تم ضبطها. ولا توجد أيضًا طريقة للتحكّم في وقت إرسال المتصفّح للتقارير، فهو يسجّلها ويضعها في قائمة انتظار ويرسلها تلقائيًا في وقت مناسب.

وهذا يعني أنّه لا داعي للقلق بشأن الأداء عند استخدام Reporting API.

يتم إرسال التقارير مع تأخير يصل إلى دقيقة واحدة لزيادة فرص إرسال التقارير على دفعات. يؤدي ذلك إلى توفير معدل نقل البيانات لمراعاة اتصال المستخدم بالشبكة، وهو أمر مهم بشكل خاص على الأجهزة الجوّالة. يمكن للمتصفّح أيضًا تأخير التسليم إذا كان مشغولاً بمعالجة عمل ذي أولوية أعلى، أو إذا كان المستخدم متصلاً بشبكة بطيئة أو مزدحمة في ذلك الوقت.

المشاكل المتعلّقة بالجهات الخارجية والطرف الأول

سيتم إرسال التقارير التي يتم إنشاؤها بسبب الانتهاكات أو عمليات الإيقاف النهائي التي تحدث على صفحتك إلى نقاط النهاية التي ضبطتها. ويشمل ذلك الانتهاكات التي ترتكبها النصوص البرمجية التابعة لجهات خارجية والتي يتم تشغيلها على صفحتك.

إنّ الانتهاكات أو عمليات الإيقاف النهائي التي حدثت في إطار iframe متعدّد المصادر مضمّن في صفحتك لن يتم إرسال تقارير بشأنها إلى نقاط النهاية (على الأقل ليس بشكل تلقائي). يمكن لـ iframe إعداد تقاريره الخاصة وحتى إرسال تقارير إلى خدمة إعداد التقارير في موقعك الإلكتروني، أي الطرف الأول، ولكن هذا الأمر يعود إلى الموقع الإلكتروني الذي تم تأطيره. يُرجى العِلم أيضًا أنّ معظم التقارير يتم إنشاؤها فقط في حال انتهاك سياسة الصفحة، وأنّ سياسات صفحتك وسياسات iframe مختلفة.

مثال على عمليات الإيقاف نهائيًا

دعم المتصفح

يلخّص الجدول التالي مدى توافق المتصفحات مع Reporting API الإصدار 1، أي مع العنوان Reporting-Endpoints. يتوافق المتصفّح مع الإصدار 0 من Reporting API (العنوان Report-To) بالطريقة نفسها، باستثناء نوع واحد من التقارير: لا يتوافق الإصدار الجديد من Reporting API مع ميزة "تسجيل أخطاء الشبكة". يُرجى قراءة دليل نقل البيانات للاطّلاع على التفاصيل.

يلخّص هذا الجدول فقط مدى توافق report-to مع العنوان الجديد Reporting-Endpoints. يمكنك الاطّلاع على نصائح نقل تقارير CSP إذا أردت نقل البيانات إلى Reporting-Endpoints.

استخدام Reporting API

تحديد المكان الذي يجب إرسال التقارير إليه

أمامك خياران:

• إرسال التقارير إلى خدمة حالية لجمع التقارير
• إرسال التقارير إلى أداة تجميع تقارير تنشئها وتديرها بنفسك

الخيار 1: استخدام خدمة حالية لجمع التقارير

في ما يلي بعض الأمثلة على خدمات جمع التقارير:

• report-uri
• uriports
• HeaderHawk
• Sentry

إذا كنت تعرف حلولاً أخرى، يُرجى فتح مشكلة لإعلامنا بها، وسنعدّل هذا المنشور.

إلى جانب الأسعار، يجب مراعاة النقاط التالية عند اختيار أداة لجمع التقارير: 🧐

• هل يتيح هذا الجامع جميع أنواع التقارير؟ على سبيل المثال، لا تتيح بعض حلول نقاط النهاية لإعداد التقارير تقارير COOP/COEP.
• هل توافق على مشاركة أي من عناوين URL الخاصة بتطبيقك مع جامع تقارير تابع لجهة خارجية؟ وحتى إذا أزال المتصفّح المعلومات الحسّاسة من عناوين URL هذه، قد يتم تسريب المعلومات الحسّاسة بهذه الطريقة. إذا كان ذلك يبدو محفوفًا بالمخاطر بالنسبة إلى تطبيقك، يمكنك تشغيل نقطة نهاية عملية الإبلاغ الخاصة بك.

الخيار 2: إنشاء أداة جمع التقارير وتشغيلها

إنّ إنشاء خادم خاص بك يتلقّى التقارير ليس أمرًا بسيطًا. للبدء، يمكنك إنشاء نسخة من نموذجنا البسيط. تم إنشاء هذا التطبيق باستخدام Express ويمكنه تلقّي التقارير وعرضها.

عند إنشاء أداة جمع التقارير الخاصة بك:

• ابحث عن طلبات POST التي تتضمّن Content-Type بقيمة application/reports+json للتعرّف على طلبات التقارير التي يرسلها المتصفّح إلى نقطة النهاية.
• إذا كانت نقطة النهاية موجودة في مصدر مختلف عن موقعك الإلكتروني، تأكَّد من أنّها تتيح طلبات التحقّق المسبق من CORS.

الخيار 3: الجمع بين الخيارَين 1 و2

قد ترغب في السماح لمقدّم خدمة معيّن بالتعامل مع بعض أنواع التقارير، ولكنك قد تفضّل استخدام حلّ داخلي للأنواع الأخرى.

في هذه الحالة، اضبط نقاط نهاية متعددة على النحو التالي:

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

ضبط عنوان Reporting-Endpoints

اضبط عنوان الاستجابة Reporting-Endpoints. يجب أن تكون قيمته واحدة أو سلسلة من أزواج المفتاح والقيمة مفصولة بفواصل:

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

في حال نقل البيانات من Reporting API القديمة إلى Reporting API الجديدة، قد يكون من المنطقي ضبط كلّ من Reporting-Endpoints وReport-To. يمكنك الاطّلاع على التفاصيل في دليل نقل البيانات. على وجه الخصوص، إذا كنت تستخدم ميزة إعداد التقارير لمخالفات Content-Security-Policy باستخدام التوجيه report-uri فقط، يُرجى مراجعة خطوات نقل البيانات لإعداد تقارير CSP.

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

المفاتيح (أسماء نقاط النهاية)

يمكن أن يكون كل مفتاح اسمًا من اختيارك، مثل main-endpoint أو endpoint-1. يمكنك اختيار ضبط نقاط نهاية مختلفة بأسماء مختلفة لأنواع التقارير المختلفة، مثل my-coop-endpoint وmy-csp-endpoint. وبذلك، يمكنك توجيه التقارير إلى نقاط نهاية مختلفة حسب نوعها.

إذا أردت تلقّي تقارير التدخّل أو الإيقاف أو الأعطال أو مزيج من هذه التقارير، اضبط نقطة نهاية باسم default.

إذا لم يحدّد عنوان Reporting-Endpoints نقطة نهاية default، لن يتم إرسال التقارير من هذا النوع (على الرغم من أنّه سيتم إنشاؤها).

القيم (عناوين URL)

وكل قيمة هي عنوان URL من اختيارك، وسيتم إرسال التقارير إليه. يعتمد عنوان URL الذي سيتم ضبطه هنا على ما قرّرته في الخطوة 1.

عنوان URL لنقطة النهاية:

• يجب أن يبدأ بشرطة مائلة (/)، ولا تتوفّر المسارات النسبية.
• يمكن أن تكون متعدّدة المصادر، ولكن في هذه الحالة لا يتم إرسال بيانات الاعتماد مع التقارير.

أمثلة

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

يمكنك بعد ذلك استخدام كل نقطة نهاية مُسمّاة في السياسة المناسبة، أو استخدام نقطة نهاية واحدة في جميع السياسات.

أين يمكن ضبط العنوان؟

في واجهة Reporting API الجديدة، وهي الواجهة التي نتناولها في هذا المنشور، يتم تحديد نطاق التقارير حسب المستندات. وهذا يعني أنّه بالنسبة إلى مصدر معيّن، يمكن لمستندات مختلفة، مثل site.example/page1 وsite.example/page2، إرسال تقارير إلى نقاط نهاية مختلفة.

لتلقّي تقرير عن الانتهاكات أو عمليات الإيقاف النهائي التي تحدث على أي صفحة من صفحات موقعك الإلكتروني، اضبط العنوان كبرنامج وسيط في جميع الردود.

إليك مثال في Express:

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

تعديل سياساتك

بعد ضبط العنوان Reporting-Endpoints، أضِف توجيه report-to إلى كل عنوان سياسة تريد تلقّي تقارير عن انتهاكاتها. يجب أن تكون قيمة report-to إحدى نقاط النهاية المسماة التي أعددتها.

يمكنك استخدام نقطة النهاية المتعدّدة لسياسات متعدّدة، أو استخدام نقاط نهاية مختلفة على مستوى السياسات.

لا يلزم توفّر report-to لتقارير الإيقاف النهائي والتدخّل والتعطُّل. لا ترتبط هذه التقارير بأي سياسة. ويتم إنشاؤها طالما تم إعداد نقطة نهاية default وإرسالها إلى نقطة نهاية 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

تصحيح أخطاء إعداد التقارير

إنشاء التقارير بشكل مقصود

عند إعداد Reporting API، ستحتاج على الأرجح إلى انتهاك سياساتك عمدًا للتحقّق مما إذا كان يتم إنشاء التقارير وإرسالها على النحو المتوقّع.

توفير الوقت

قد يتم إرسال التقارير بتأخير يبلغ دقيقة واحدة تقريبًا، وهو وقت طويل عند تصحيح الأخطاء. 😴 لحسن الحظ، عند تصحيح الأخطاء في Chrome، يمكنك استخدام العلامة --short-reporting-delay لتلقّي التقارير فور إنشائها.

نفِّذ الأمر التالي في الوحدة الطرفية لتفعيل هذا الخيار:

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

استخدام "أدوات مطوري البرامج"

في Chrome، استخدِم "أدوات مطوّري البرامج" للاطّلاع على التقارير التي تم إرسالها أو سيتم إرسالها.

اعتبارًا من تشرين الأول (أكتوبر) 2021، أصبحت هذه الميزة تجريبية. لاستخدامها، اتّبِع الخطوات التالية:

1. استخدام الإصدار 96 من Chrome والإصدارات الأحدث (يمكنك التحقّق من الإصدار عن طريق كتابة chrome://version في المتصفّح)
2. اكتب أو الصِق chrome://flags/#enable-experimental-web-platform-features في شريط العناوين في Chrome.
3. انقر على مفعَّل.
4. إعادة تشغيل المتصفّح
5. افتح "أدوات مطوري البرامج في Chrome".
6. في "أدوات مطوّري البرامج في Chrome"، افتح "الإعدادات". ضمن "التجارب"، انقر على تفعيل لوحة Reporting API في لوحة "التطبيق".
7. أعِد تحميل "أدوات مطوّري البرامج".
8. أعِد تحميل الصفحة. ستظهر التقارير التي تنشئها الصفحة التي تكون "أدوات مطوّري البرامج" مفتوحة فيها في لوحة التطبيق ضمن Reporting API في "أدوات مطوّري البرامج في Chrome".

حالة التقرير

يخبرك عمود الحالة ما إذا تم إرسال بلاغ بنجاح.

تتم إزالة التقارير بعد فترة، سواء تم إرسالها بنجاح أم لا.

تحديد المشاكل وحلّها

هل لا يتم إنشاء التقارير أو لا يتم إرسالها إلى نقطة النهاية على النحو المتوقع؟ إليك بعض النصائح لتحديد المشاكل وحلّها.

لم يتم إنشاء التقارير

تم إنشاء التقارير التي تظهر في "أدوات مطوّري البرامج" بشكلٍ صحيح. إذا كان التقرير الذي تتوقّعه لا يظهر في هذه القائمة، اتّبِع الخطوات التالية:

• يُرجى التحقّق من report-to في سياساتك. وفي حال ضبطها بشكل غير صحيح، لن يتم إنشاء تقرير. انتقِل إلى تعديل سياساتك لحلّ هذه المشكلة. هناك طريقة أخرى لتحديد المشاكل وحلّها، وهي التحقّق من وحدة تحكّم "أدوات مطوّري البرامج" في Chrome: إذا ظهر خطأ في وحدة التحكّم بسبب الانتهاك الذي توقّعته، يعني ذلك أنّ سياستك تم ضبطها بشكل صحيح على الأرجح.
• يُرجى العِلم أنّ هذه القائمة ستعرض فقط التقارير التي تم إنشاؤها للمستند الذي تم فتح "أدوات مطوري البرامج" فيه. على سبيل المثال، إذا كان موقعك الإلكتروني site1.example يتضمّن إطار iframe site2.example ينتهك سياسة معيّنة وبالتالي يؤدي إلى إنشاء تقرير، لن يظهر هذا التقرير في "أدوات مطوّري البرامج" إلا إذا فتحت إطار iframe في نافذة منفصلة وفتحت "أدوات مطوّري البرامج" لهذه النافذة.

يتم إنشاء التقارير ولكن لا يتم إرسالها أو استلامها

ماذا لو كان بإمكانك الاطّلاع على تقرير في "أدوات مطوّري البرامج"، ولكن لم يتلقَّ نقطة النهاية هذا التقرير؟

• تأكَّد من استخدام فترات تأخير قصيرة. قد يكون سبب عدم ظهور التقرير هو أنّه لم يتم إرساله بعد.

• تحقَّق من إعدادات عنوان Reporting-Endpoints. إذا كانت هناك مشكلة في التقرير، لن يتم إرسال التقرير الذي تم إنشاؤه بشكل صحيح. في هذه الحالة، ستبقى حالة التقرير في "أدوات مطوري البرامج" على النحو التالي: Queued (قد تنتقل إلى Pending، ثم تعود سريعًا إلى Queued عند إجراء محاولة تسليم). في ما يلي بعض الأخطاء الشائعة التي قد تؤدي إلى حدوث ذلك:

• يتم استخدام نقطة النهاية ولكن لم يتم ضبطها. مثال:

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

• نقطة النهاية default غير متوفّرة. سيتم إرسال بعض أنواع التقارير، مثل تقارير الإيقاف النهائي والتدخّل، إلى نقطة النهاية التي تحمل الاسم default فقط. يمكنك الاطّلاع على مزيد من المعلومات في مقالة ضبط عنوان Reporting-Endpoints.

• ابحث عن مشاكل في بنية عناوين السياسات، مثل علامات الاقتباس المفقودة. الاطّلاع على التفاصيل

• تأكَّد من أنّ نقطة النهاية يمكنها معالجة الطلبات الواردة.

  • تأكَّد من أنّ نقطة النهاية تتيح طلبات CORS المسبقة. إذا لم يكن كذلك، لن يتمكّن من تلقّي التقارير.

  • اختبِر سلوك نقطة النهاية. لإجراء ذلك، بدلاً من إنشاء التقارير يدويًا، يمكنك محاكاة المتصفّح من خلال إرسال طلبات إلى نقطة النهاية تبدو مثل الطلبات التي يرسلها المتصفّح. نفِّذ ما يلي:

  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
  

  يجب أن يستجيب نقطة النهاية برمز نجاح (200 أو رمز استجابة آخر يشير إلى النجاح 2xx). وإذا لم يحدث ذلك، تكون هناك مشكلة في إعداداتها.

آليات الإبلاغ ذات الصلة

إعداد التقارير فقط

تعمل عناوين سياسة -Report-Only وReporting-Endpoints معًا.

ستتلقّى نقاط النهاية التي تم ضبطها في Reporting-Endpoints وتحديدها في حقل report-to ضمن Content-Security-Policy وCross-Origin-Embedder-Policy وCross-Origin-Opener-Policy تقارير عند انتهاك هذه السياسات.

يمكن أيضًا تحديد نقاط النهاية التي تم ضبطها في Reporting-Endpoints في حقل report-to ضمن Content-Security-Policy-Report-Only وCross-Origin-Embedder-Policy-Report-Only وCross-Origin-Opener-Policy-Report-Only. سيتلقّون أيضًا تقارير عند انتهاك هذه السياسات.

على الرغم من إرسال التقارير في كلتا الحالتَين، لا تفرض عناوين -Report-Only السياسات، أي لن يتم تعطيل أي شيء أو حظره فعليًا، ولكن ستتلقّى تقارير بما كان سيتم تعطيله أو حظره.

ReportingObserver

يمكن أن تساعدك واجهة برمجة التطبيقات ReportingObserver المستندة إلى JavaScript في رصد التحذيرات من جهة العميل.

تنشئ السمة ReportingObserver والعنوان Reporting-Endpoints تقارير تبدو متشابهة، ولكنّها تتيح حالات استخدام مختلفة قليلاً.

استخدِم ReportingObserver في الحالات التالية:

• إذا أردت فقط مراقبة عمليات الإيقاف النهائي أو تدخّلات المتصفّح تعرض واجهة برمجة التطبيقات ReportingObserver تحذيرات من جهة العميل، مثل عمليات الإيقاف النهائي وتدخّلات المتصفّح، ولكن على عكس Reporting-Endpoints، لا تلتقط أي أنواع أخرى من التقارير، مثل انتهاكات CSP أو COOP/COEP.
• عليك التعامل مع هذه الانتهاكات في الوقت الفعلي. يتيح لك ReportingObserver إرفاق دالة رد اتصال بحدث انتهاك.
• إذا أردت إرفاق معلومات إضافية بتقرير للمساعدة في تصحيح الأخطاء، يمكنك استخدام دالة الاستدعاء المخصّصة.

ومن الاختلافات الأخرى أنّ ReportingObserver يتم ضبطه من جهة العميل فقط: يمكنك استخدامه حتى إذا لم يكن لديك إمكانية التحكّم في العناوين من جهة الخادم ولا يمكنك ضبط Reporting-Endpoints.

محتوى إضافي للقراءة

• دليل نقل البيانات من الإصدار 0 إلى الإصدار 1 من Reporting API
• ReportingObserver
• المواصفات: واجهة Reporting API القديمة (الإصدار 0)
• المواصفات: Reporting API الجديدة (الإصدار 1)

شكرًا جزيلاً لـ "إيان كليلاند" و"إيجي كيتامورا" و"ميليكا ميهاجليجا" على مراجعاتهم واقتراحاتهم بشأن هذا المستند.