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

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

Maud Nalpas

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

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

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

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

العرض التوضيحي والرمز البرمجي

يمكنك الاطّلاع على واجهة برمجة التطبيقات Reporting API في العمل اعتبارًا من Chrome 96 والإصدارات الأحدث (Chrome الإصدار التجريبي أو Canary، اعتبارًا من تشرين الأول (أكتوبر) 2021).

نظرة عامة

لنفترض أنّ موقعك الإلكتروني 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 مختلفة.

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

دعم المتصفح

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

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

استخدام Reporting API

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

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

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

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

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

• report-uri
• uriports

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

بالإضافة إلى السعر، ننصحك بالأخذ في الاعتبار النقاط التالية عند اختيار أداة جمع التقارير: 🧐

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

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

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

1. انتقِل إلى أداة جمع التقارير الجاهزة.

2. انقر على إنشاء ريمكس لتعديل لجعل المشروع قابلاً للتعديل.

3. لديك الآن نسخة طبق الأصل. ويمكنك تخصيصها لأغراضك الخاصة.

إذا كنت لا تستخدم النص النموذجي وكنت تنشئ خادمك من البداية:

• ابحث عن طلبات 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

مثال على الرمز

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

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

إنشاء التقارير عن قصد

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

توفير الوقت

قد يتم إرسال التقارير بعد تأخير لمدة دقيقة تقريبًا، وهي مدة طويلة عند تصحيح الأخطاء. PII لحسن الحظ، عند تصحيح الأخطاء في 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 في شريط عناوين URL في متصفِّح 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 API في ملاحظة التحذيرات من جهة العميل.

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

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

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

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

مراجع إضافية

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

الصورة الرئيسية من إنشاء Nine Koepfer / @enka80 على Unsplash، تم تعديلها. نشكر إيان كليلاند وإيجي كاتامورا وميليكا ميهايليجا على مراجعاتهم واقتراحاتهم بشأن هذه المقالة.