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

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

Maud Nalpas
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 لمساعدتك في مراقبة العديد من أنواع التحذيرات أو المشاكل المثيرة للاهتمام التي تحدث في جميع أنحاء موقعك الإلكتروني:

نوع التقرير مثال على حالة يتم فيها إنشاء تقرير
انتهاك سياسة أمان المحتوى (CSP) (المستوى 3 فقط) لقد ضبطت سياسة "Content-Security-Policy" (CSP) على إحدى صفحاتك، ولكن الصفحة تحاول تحميل نص برمجي غير مسموح به من خلال سياسة أمان المحتوى (CSP).
مخالفة COOP لقد ضبطت Cross-Origin-Opener-Policy على صفحة، ولكن نافذة من مصدر مختلف تحاول التفاعل مباشرةً مع المستند.
انتهاك COEP لقد ضبطت Cross-Origin-Embedder-Policy على صفحة، ولكنّ المستند يتضمّن إطار iframe من مصدر مختلف لم يتم تفعيله ليتم تحميله من خلال مستندات من مصادر مختلفة.
انتهاك سياسة المستندات تحتوي الصفحة على سياسة مستندات تمنع استخدام document.write، ولكن يحاول نص برمجي استدعاء document.write.
انتهاك سياسة الأذونات تحتوي الصفحة على سياسة أذونات تمنع استخدام الميكروفون، ونص برمجي يطلب إدخال صوت.
تحذير بشأن إيقاف الميزة نهائيًا تستخدم الصفحة واجهة برمجة تطبيقات تم إيقافها نهائيًا أو سيتم إيقافها نهائيًا، أي يتم استدعاءها بشكل مباشر أو من خلال نص برمجي لجهة خارجية بمستوى أعلى.
التدخل تحاول الصفحة تنفيذ إجراء يقرر المتصفّح عدم تنفيذه لأسباب تتعلّق بالأمان أو الأداء أو تجربة المستخدم. مثال في Chrome: تستخدم الصفحة document.write على الشبكات البطيئة أو تستدعي navigator.vibrate في إطار من مصدر مختلف لم يتفاعل معه المستخدم بعد.
حادث سير يتعطّل المتصفّح عندما يكون موقعك الإلكتروني مفتوحًا.

التقارير

كيف تبدو التقارير؟

يُرسِل المتصفّح التقارير إلى نقطة النهاية التي ضبطتها. ويُرسِل طلبات بالشكل التالي:

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

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

الحقل الوصف
age عدد المللي ثانية بين الطابع الزمني للتقرير والوقت الحالي
body بيانات التقرير الفعلية، متسلسلة في سلسلة JSON. يتم تحديد الحقول الواردة في body للتقرير من خلال type للتقرير. ⚠️ تتضمّن التقارير من الأنواع المختلفة أقسامًا مختلفة. وللاطّلاع على النص الأساسي لكل نوع تقرير، راجِع نقطة نهاية إعداد التقارير التجريبية واتّبِع التعليمات لإنشاء أمثلة على التقارير.
type نوع تقرير، على سبيل المثال csp-violation أو coep.
url عنوان المستند أو العامل الذي تم إنشاء التقرير منه يتم إزالة البيانات الحسّاسة، مثل اسم المستخدم وكلمة المرور والجزء من عنوان URL هذا.
user_agent عنوان User-Agent للطلب الذي تم إنشاء التقرير منه.

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

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

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

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

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

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

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

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

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

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

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

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

دعم المتصفح

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

نوع التقرير Chrome Chrome لأجهزة iOS Safari Firefox Edge
انتهاك سياسة أمان المحتوى (CSP) (المستوى 3 فقط)* ✔ نعم ✔ نعم ✔ نعم ✘ لا ✔ نعم
تسجيل أخطاء الشبكة ✘ لا ✘ لا ✘ لا ✘ لا ✘ لا
انتهاك سياسة مشاركة المعلومات (COOP/COEP) ✔ نعم ✘ لا ✔ نعم ✘ لا ✔ نعم
جميع الأنواع الأخرى: انتهاك سياسة المستندات، الإيقاف النهائي، التدخل، الأعطال ✔ نعم ✘ لا ✘ لا ✘ لا ✔ نعم

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

استخدام Reporting API

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

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

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

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

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

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

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

  • هل تتيح أداة التجميع هذه استخدام جميع أنواع التقارير؟ على سبيل المثال، لا تتوافق بعض حلول نقاط النهاية لإعداد التقارير مع تقارير 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 هي إحدى نقاط النهاية المُسمّاة التي أعددتها.

لا يلزم استخدام 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

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

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

حالة التقرير

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

الحالة الوصف
Success أرسل المتصفّح التقرير وردّت نقطة النهاية برمز نجاح (200 أو رمز استجابة نجاح آخر 2xx).
Pending يحاول المتصفّح حاليًا إرسال التقرير.
Queued تم إنشاء التقرير ولا يحاول المتصفّح إرساله حاليًا. يظهر التقرير على أنّه Queued في إحدى الحالتَين التاليتَين:
  • التقرير جديد، وينتظر المتصفّح لمعرفة ما إذا كان سيصل المزيد من التقارير قبل محاولة إرساله.
  • التقرير ليس جديدًا، فقد حاول المتصفّح إرسال هذا التقرير وتعذّر عليه ذلك، وهو في انتظار إعادة المحاولة.
MarkedForRemoval بعد إعادة المحاولة لبعض الوقت (Queued)، توقّف المتصفّح عن محاولة إرسال التقرير، وستتم إزالته قريبًا من قائمة التقارير لإرساله.

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

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

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

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

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

  • راجِع 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"

يجب إرسال تقارير انتهاك سياسة المستندات إلى endpoint-1، ولكن لم يتم ضبط اسم نقطة النهاية هذه في Reporting-Endpoints.

  • نقطة نهاية 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.

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

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