مراقبة تطبيق الويب باستخدام 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. انقر على Remix to Edit (إنشاء ريمكس لتعديل المحتوى) ليصبح المشروع قابلاً للتعديل.

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، من المحتمل أن تحتاج إلى انتهاك سياساتك عمدًا للتحقّق مما إذا كان يتم إنشاء التقارير وإرسالها على النحو المتوقّع. للاطّلاع على مثال على رمز ينتهك السياسات وينفّذ إجراءات أخرى سيئة تؤدي إلى توليد تقارير من جميع الأنواع، يمكنك الاطّلاع على الإصدار التجريبي.

توفير الوقت

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

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

مراجع إضافية

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

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