از Reporting API برای نظارت بر نقضهای امنیتی، تماسهای API منسوخ شده و موارد دیگر استفاده کنید.
برخی از خطاها فقط در تولید رخ می دهد. شما آنها را به صورت محلی یا در طول توسعه نخواهید دید زیرا کاربران واقعی ، شبکه های واقعی و دستگاه های واقعی بازی را تغییر می دهند. Reporting API کمک میکند تا برخی از این خطاها را پیدا کنید - مانند نقضهای امنیتی یا تماسهای API منسوخ شده و به زودی منسوخ شده در سراسر سایت شما، و آنها را به نقطه پایانی که مشخص کردهاید منتقل میکند.
این به شما امکان می دهد آنچه را که می خواهید نظارت کنید از طریق سرصفحه های HTTP اعلام کنید و توسط مرورگر اداره می شود.
راهاندازی Reporting API به شما آرامش میدهد که وقتی کاربران این نوع خطاها را تجربه میکنند، متوجه خواهید شد، بنابراین میتوانید آنها را برطرف کنید.
این پست به آنچه که این API می تواند انجام دهد و نحوه استفاده از آن را پوشش می دهد. بیایید شیرجه بزنیم!
نسخه ی نمایشی و کد
از Chrome 96 و جدیدتر (Chrome Beta یا Canary، از اکتبر 2021)، API گزارش را در عمل مشاهده کنید.
نمای کلی
فرض کنید سایت شما، site.example
، دارای یک Content-Security-Policy و یک Document-Policy است. نمیدونی اینا چیکار میکنن؟ اشکالی ندارد، شما همچنان می توانید این مثال را درک کنید.
شما تصمیم میگیرید که سایت خود را نظارت کنید تا بدانید چه زمانی این خطمشیها نقض میشوند، اما همچنین به این دلیل که میخواهید مراقب APIهای منسوخ شده یا به زودی منسوخشدهتان باشید که ممکن است پایگاه کد شما از آنها استفاده کند.
برای انجام این کار، یک سرصفحه 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، یک گزارش نقض Document-Policy و یک گزارش Deprecation ایجاد میکند که این مشکلات را نشان میدهد.
مرورگر با تأخیر کوتاهی - حداکثر یک دقیقه - گزارش ها را به نقطه پایانی که برای این نوع نقض پیکربندی شده است ارسال می کند. گزارش ها خارج از باند توسط خود مرورگر (نه توسط سرور و نه توسط سایت شما) ارسال می شوند.
نقطه پایانی این گزارش ها را دریافت می کند.
اکنون میتوانید به گزارشهای مربوط به این نقاط پایانی دسترسی داشته باشید و آنچه را که اشتباه رخ داده است نظارت کنید. شما آماده شروع عیب یابی مشکلی هستید که کاربران شما را تحت تاثیر قرار می دهد.
گزارش نمونه
{
"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"
}
از موارد و انواع گزارش استفاده کنید
گزارش API را می توان به گونه ای پیکربندی کرد که به شما کمک کند بسیاری از هشدارها یا مسائل جالبی را که در سرتاسر سایت شما اتفاق می افتد نظارت کنید:
نوع گزارش | مثالی از موقعیتی که در آن یک گزارش تولید می شود |
---|---|
نقض CSP (فقط سطح 3) | شما یک Content-Security-Policy (CSP) در یکی از صفحات خود تنظیم کرده اید، اما صفحه در تلاش است تا اسکریپتی را بارگیری کند که توسط CSP شما مجاز نیست. |
نقض COOP | شما روی یک صفحه یک Cross-Origin-Opener-Policy تنظیم کرده اید، اما یک پنجره متقاطع در حال تلاش برای تعامل مستقیم با سند است. |
نقض COEP | شما یک Cross-Origin-Embedder-Policy را در یک صفحه تنظیم کردهاید، اما سند شامل یک iframe متقاطع است که بارگیری توسط اسناد متقاطع را انتخاب نکرده است. |
نقض خط مشی سند | صفحه دارای یک خط مشی سند است که از استفاده از document.write جلوگیری می کند، اما یک اسکریپت سعی می کند document.write فراخوانی کند. |
نقض خط مشی مجوزها | صفحه دارای یک خطمشی مجوز است که از استفاده از میکروفون جلوگیری میکند و اسکریپتی که ورودی صوتی را درخواست میکند. |
هشدار منسوخ شدن | صفحه از یک API استفاده می کند که منسوخ شده یا منسوخ خواهد شد. آن را مستقیماً یا از طریق یک اسکریپت شخص ثالث سطح بالا فراخوانی می کند. |
مداخله | این صفحه در تلاش است کاری انجام دهد که مرورگر به دلایل امنیتی، عملکرد یا تجربه کاربر تصمیم به رعایت آن نکند. مثال در 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 API v1 را خلاصه میکند که با سربرگ Reporting-Endpoints
است. پشتیبانی مرورگر برای Reporting API v0 ( Report-To
header) یکسان است، به جز یک نوع گزارش: ثبت خطای شبکه در گزارش API جدید پشتیبانی نمیشود. راهنمای مهاجرت را برای جزئیات بخوانید.
نوع گزارش | کروم | کروم iOS | سافاری | فایرفاکس | لبه |
---|---|---|---|---|---|
نقض CSP (فقط سطح 3)* | ✔ بله | ✔ بله | ✔ بله | ✘ خیر | ✔ بله |
ثبت خطای شبکه | ✘ خیر | ✘ خیر | ✘ خیر | ✘ خیر | ✘ خیر |
نقض COOP/COEP | ✔ بله | ✘ خیر | ✔ بله | ✘ خیر | ✔ بله |
همه انواع دیگر: نقض خطمشی سند، منسوخ شدن، مداخله، خرابی | ✔ بله | ✘ خیر | ✘ خیر | ✘ خیر | ✔ بله |
این جدول فقط پشتیبانی از report-to
با سربرگ جدید Reporting-Endpoints
خلاصه می کند. اگر به دنبال مهاجرت به Reporting-Endpoints
هستید ، نکات مهاجرت گزارش CSP را بخوانید.
با استفاده از Reporting API
تصمیم بگیرید که گزارش ها باید کجا ارسال شوند
شما دو گزینه دارید:
- گزارشها را به یک سرویس جمعآوری گزارش موجود ارسال کنید.
- گزارشها را به جمعآوری گزارشدهی که خودتان میسازید و اداره میکنید، ارسال کنید.
گزینه 1: از یک سرویس جمع آوری گزارش موجود استفاده کنید
چند نمونه از خدمات جمع آوری گزارش عبارتند از:
اگر راهحلهای دیگری میشناسید، موضوعی را باز کنید تا به ما اطلاع دهید، و ما این پست را بهروزرسانی میکنیم!
در انتخاب گزارش گردآورنده علاوه بر قیمت، نکات زیر را در نظر بگیرید: 🧐
- آیا این گردآورنده همه انواع گزارش را پشتیبانی می کند؟ به عنوان مثال، همه راه حل های نقطه پایانی گزارش از گزارش های COOP/COEP پشتیبانی نمی کنند.
- آیا به اشتراک گذاری هر یک از URL های برنامه خود با یک گردآورنده گزارش شخص ثالث راحت هستید؟ حتی اگر مرورگر اطلاعات حساس را از این URL ها حذف کند، ممکن است اطلاعات حساس از این طریق به بیرون درز کند . اگر این برای برنامه شما بسیار خطرناک به نظر می رسد، نقطه پایانی گزارش خود را اجرا کنید.
گزینه 2: جمع آوری گزارش خود را بسازید و راه اندازی کنید
ساختن سرور خود که گزارشها را دریافت میکند چندان هم پیش پا افتاده نیست. برای شروع، می توانید دیگ بخار سبک وزن ما را دوشاخه کنید. این با Express ساخته شده است و می تواند گزارش ها را دریافت و نمایش دهد.
به جمع کننده گزارش دیگ بخار بروید.
روی Remix to Edit کلیک کنید تا پروژه قابل ویرایش باشد.
شما اکنون کلون خود را دارید! شما می توانید آن را برای اهداف خود سفارشی کنید.
اگر از boilerplate استفاده نمی کنید و سرور خود را از ابتدا می سازید:
- درخواستهای
POST
را باContent-Type
ofapplication/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"
اگر از 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"
سپس میتوانید از هر نقطه پایانی نامگذاریشده در خطمشی مناسب استفاده کنید، یا از یک نقطه پایانی در همه خطمشیها استفاده کنید.
هدر را کجا تنظیم کنیم؟
در گزارش 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، احتمالاً باید عمداً خطمشیهای خود را نقض کنید تا بررسی کنید که آیا گزارشها مطابق انتظار تولید و ارسال میشوند یا خیر. برای مشاهده نمونه کدی که خطمشیها را نقض میکند و کارهای بد دیگری را انجام میدهد که انواع گزارشها را تولید میکند، نسخه آزمایشی را بررسی کنید.
صرفه جویی در زمان
گزارشها ممکن است با تأخیر ارسال شوند - حدود یک دقیقه، که در هنگام اشکالزدایی زمان طولانی است. 😴 خوشبختانه، هنگام اشکال زدایی در کروم، می توانید از پرچم --short-reporting-delay
برای دریافت گزارش ها به محض تولید استفاده کنید.
این دستور را در ترمینال خود اجرا کنید تا این پرچم روشن شود:
YOUR_PATH/TO/EXECUTABLE/Chrome --short-reporting-delay
از DevTools استفاده کنید
در Chrome، از DevTools برای مشاهده گزارشهایی که ارسال شده یا ارسال خواهد شد، استفاده کنید.
از اکتبر 2021، این ویژگی آزمایشی است. برای استفاده از آن، مراحل زیر را دنبال کنید:
- از کروم نسخه 96 و جدیدتر استفاده کنید (با تایپ کردن
chrome://version
در مرورگر خود بررسی کنید) -
chrome://flags/#enable-experimental-web-platform-features
در نوار URL Chrome تایپ یا جایگذاری کنید. - روی Enabled کلیک کنید.
- مرورگر خود را مجددا راه اندازی کنید.
- Chrome DevTools را باز کنید.
- در Chrome DevTools، تنظیمات را باز کنید. در بخش آزمایشها، روی فعال کردن پانل API گزارش در پانل برنامه کلیک کنید.
- DevTools را دوباره بارگیری کنید.
- صفحه خود را دوباره بارگیری کنید گزارشهای تولید شده توسط صفحهای که DevTools در آن باز است، در پانل برنامه Chrome DevTools، در قسمت Reporting API فهرست میشود.
گزارش وضعیت
ستون وضعیت به شما می گوید که آیا گزارشی با موفقیت ارسال شده است یا خیر.
وضعیت | توضیحات |
---|---|
Success | مرورگر گزارش را ارسال کرده است و نقطه پایانی با یک کد موفقیت پاسخ داده است ( 200 یا کد پاسخ موفقیت آمیز دیگری 2xx ). |
Pending | مرورگر در حال حاضر در حال تلاش برای ارسال گزارش است. |
Queued | گزارش ایجاد شده است و مرورگر در حال حاضر سعی در ارسال آن ندارد. یک گزارش در یکی از این دو مورد به صورت Queued ظاهر می شود:
|
MarkedForRemoval | پس از مدتی تلاش مجدد ( Queued )، مرورگر تلاش برای ارسال گزارش را متوقف کرده و به زودی آن را از لیست گزارش های ارسالی خود حذف خواهد کرد. |
گزارشها پس از مدتی حذف میشوند، چه با موفقیت ارسال شوند یا نه.
عیب یابی
آیا گزارش ها همانطور که انتظار می رود به نقطه پایانی شما ارسال نمی شود یا تولید نمی شود؟ در اینجا چند نکته برای رفع این مشکل وجود دارد.
گزارش ایجاد نمی شود
گزارش هایی که در DevTools نشان داده می شوند به درستی تولید شده اند. اگر گزارش مورد انتظار شما در این لیست نمایش داده نمی شود:
-
report-to
در خطمشیهای خود بررسی کنید. اگر این پیکربندی اشتباه باشد، گزارشی ایجاد نخواهد شد. برای رفع این مشکل، به ویرایش خطمشیهای خود بروید. یک راه دیگر برای عیب یابی این است که کنسول DevTools در کروم را بررسی کنید: اگر خطایی در کنسول برای نقض مورد انتظار شما ظاهر شد، به این معنی است که خط مشی شما احتمالاً به درستی پیکربندی شده است. - به خاطر داشته باشید که فقط گزارشهایی که برای سندی که DevTools در آن باز است ایجاد شدهاند در این لیست نشان داده میشوند. یک مثال: اگر سایت شما
site1.example
یک iframesite2.example
را تعبیه کند که یک خط مشی را نقض می کند و از این رو گزارشی تولید می کند، این گزارش تنها در صورتی در DevTools نشان داده می شود که iframe را در پنجره خودش باز کنید و DevTools را برای آن پنجره باز کنید.
گزارش ها تولید می شوند اما ارسال نمی شوند یا دریافت نمی شوند
اگر بتوانید گزارشی را در DevTools ببینید، اما نقطه پایانی شما آن را دریافت نکند، چه؟
- حتما از تاخیرهای کوتاه استفاده کنید. شاید دلیل اینکه گزارشی را نمی بینید این باشد که هنوز ارسال نشده است!
پیکربندی سرصفحه
Reporting-Endpoints
خود را بررسی کنید. اگر مشکلی در آن وجود داشته باشد، گزارشی که به درستی ایجاد شده باشد ارسال نخواهد شد. در DevTools، وضعیت گزارش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
تنظیم کنید، می توانید از آن استفاده کنید.
در ادامه مطلب
- راهنمای مهاجرت از Reporting API v0 به v1
- ReportingObserver
- مشخصات: API گزارش قدیمی (v0)
- مشخصات: New Reporting API (v1)
تصویر قهرمان توسط Nine Koepfer / @enka80 در Unsplash ، ویرایش شده است. با تشکر فراوان از ایان کللند، ایجی کیتامورا و میلیکا میهایلیجا برای نظرات و پیشنهاداتشان در مورد این مقاله.