استخدِم Reporting API لمراقبة انتهاكات الأمان وطلبات البيانات من واجهات برمجة التطبيقات المتوقّفة نهائيًا وغير ذلك.
تحدث بعض الأخطاء في مرحلة الإنتاج فقط. ولن تظهر لك هذه المشاكل على الجهاز أو أثناء تطوير التطبيق، لأنّ المستخدمين والشبكات والأجهزة كلها تؤثر في الأداء. تساعد 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 مختلفة.
مثال على عمليات الإيقاف النهائي
دعم المتصفح
يلخّص الجدول أدناه توافق المتصفّحات مع الإصدار 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 ويمكنه تلقّي التقارير وعرضها.
انتقِل إلى أداة تجميع تقارير النصوص النموذجية.
انقر على Remix to Edit (إنشاء ريمكس لتعديله) ليصبح المشروع قابلاً للتعديل.
لديك الآن نسخة طبق الأصل. ويمكنك تخصيصها لأغراضك الخاصة.
إذا كنت لا تستخدم النص النموذجي وكنت تنشئ خادمك من البداية:
- ابحث عن طلبات
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
مثال على الرمز
لعرض كل هذا في السياق، إليك مثال على خادم عقدة يستخدم Express ويجمع كل الأجزاء التي تمت مناقشتها في هذه المقالة. ويوضّح كيفية إعداد إعدادات إعداد التقارير لعدة أنواع مختلفة من التقارير وعرض النتائج.
تصحيح الأخطاء في إعداد التقارير
إنشاء التقارير عمدًا
عند إعداد Reporting API، من المحتمل أن تحتاج إلى انتهاك سياساتك عمدًا للتحقّق مما إذا كان يتم إنشاء التقارير وإرسالها على النحو المتوقّع. للاطّلاع على مثال على رمز ينتهك السياسات وينفّذ إجراءات أخرى سيئة تؤدي إلى توليد تقارير من جميع الأنواع، يمكنك الاطّلاع على الإصدار التجريبي.
توفير الوقت
قد يتم إرسال التقارير بعد تأخير لمدة دقيقة تقريبًا، وهي مدة طويلة عند تصحيح الأخطاء. 😴 لحسن الحظ، عند تصحيح الأخطاء في Chrome، يمكنك استخدام العلامة
--short-reporting-delay
لتلقّي التقارير فور إنشائها.
شغِّل هذا الأمر في الوحدة الطرفية لتفعيل هذا الخيار:
YOUR_PATH/TO/EXECUTABLE/Chrome --short-reporting-delay
استخدام أدوات مطوري البرامج
في Chrome، استخدِم أدوات مطوّري البرامج للاطّلاع على التقارير التي تم إرسالها أو سيتم إرسالها.
اعتبارًا من تشرين الأول (أكتوبر) 2021، أصبحت هذه الميزة تجريبية. لاستخدام هذه الميزة، اتّبِع الخطوات التالية:
- استخدام الإصدار 96 من Chrome والإصدارات الأحدث (يمكنك التحقّق من ذلك عن طريق كتابة
chrome://version
في المتصفّح) - اكتب
chrome://flags/#enable-experimental-web-platform-features
أو الصقه في شريط عناوين URL في Chrome. - انقر على مفعَّل.
- إعادة تشغيل المتصفّح
- افتح "أدوات مطوري البرامج في Chrome".
- في "أدوات مطوّري البرامج في Chrome"، افتح "الإعدادات". ضمن "التجارب"، انقر على تفعيل لوحة Reporting API في لوحة "التطبيق".
- أعِد تحميل "أدوات مطوري البرامج".
- أعِد تحميل صفحتك. سيتم إدراج التقارير التي تم إنشاؤها من الصفحة التي تكون "أدوات مطوري البرامج" مفتوحة فيها في لوحة التطبيق ضمن Reporting API في "أدوات مطوري البرامج في Chrome".
حالة التقرير
يُعلمك عمود الحالة ما إذا تم إرسال تقرير بنجاح.
الحالة | الوصف |
---|---|
Success |
أرسل المتصفّح التقرير وردّت نقطة النهاية برمز نجاح (200 أو رمز استجابة نجاح آخر 2xx ). |
Pending |
يحاول المتصفّح حاليًا إرسال التقرير. |
Queued |
تم إنشاء التقرير ولا يحاول المتصفّح إرساله حاليًا. يظهر التقرير على أنّه Queued في إحدى الحالتَين التاليتَين:
|
MarkedForRemoval |
بعد إعادة المحاولة لبعض الوقت (Queued )، توقّف المتصفّح عن محاولة إرسال التقرير، وستتم إزالته قريبًا من قائمة التقارير لإرساله. |
تتم إزالة البلاغات بعد فترة، سواء تم إرسالها بنجاح أم لا.
تحديد المشاكل وحلّها
ألا يتم إنشاء التقارير أو لم يتم إرسالها إلى نقطة النهاية على النحو المتوقع؟ إليك بعض النصائح لتحديد هذه المشكلة وحلّها.
عدم إنشاء التقارير
تم إنشاء التقارير التي تظهر في "أدوات مطوّري البرامج" بشكل صحيح. إذا لم يظهر التقرير الذي تتوقّعه في هذه القائمة:
- راجِع
report-to
في سياساتك. إذا تم إعداد ذلك بشكل خاطئ، فلن يتم إنشاء تقرير. انتقِل إلى تعديل سياساتك لمعالجة هذه المشكلة. تتوفّر طريقة إضافية لتحديد المشاكل وحلّها من خلال الاطّلاع على "وحدة التحكّم في أدوات مطوّري البرامج" في Chrome: إذا ظهر خطأ في وحدة التحكّم بسبب الانتهاك الذي توقّعته، هذا يعني أنّ سياستك قد تم ضبطها بشكل صحيح. - يُرجى العِلم أنّه لن تظهر في هذه القائمة سوى التقارير التي تم إنشاؤها للمستند الذي تم فتحه في "أدوات المطوّر". على سبيل المثال، إذا كان موقعك الإلكتروني
site1.example
يدمج إطار iframesite2.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 إلى الإصدار 1 من Reporting API
- ReportingObserver
- المواصفات: Reporting API القديمة (الإصدار 0)
- المواصفات: Reporting API الجديدة (الإصدار 1)
صورة رئيسية من تأليف Nine Koepfer / @enka80 على Un التصميم، تم تعديلها. نشكر إيان كليلاند وإيجي كاتامورا وميليكا ميهايليجا على مراجعاتهم واقتراحاتهم بشأن هذه المقالة.