این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

برنامه وب خود را با گزارش API نظارت کنید

از Reporting API برای نظارت بر نقض‌های امنیتی، تماس‌های API منسوخ شده و موارد دیگر استفاده کنید.

Maud Nalpas

برخی از خطاها فقط در تولید رخ می دهد. شما آنها را به صورت محلی یا در طول توسعه نخواهید دید زیرا کاربران واقعی ، شبکه های واقعی و دستگاه های واقعی بازی را تغییر می دهند. 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 استفاده می کند که منسوخ شده یا منسوخ خواهد شد. آن را مستقیماً یا از طریق یک اسکریپت شخص ثالث سطح بالا فراخوانی می کند.
مداخله	این صفحه در تلاش است کاری انجام دهد که مرورگر به دلایل امنیتی، عملکرد یا تجربه کاربر تصمیم به رعایت آن نکند. مثال در کروم: صفحه از `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 در صفحه شما تنظیم شده باشد: API منسوخ شده که توسط اسکریپت های شخص ثالث در حال اجرا در صفحه شما خوانده می شود به نقطه پایانی شما گزارش می شود. API منسوخ شده که توسط iframe تعبیه شده در صفحه شما فراخوانی شده است به نقطه پایانی شما گزارش نخواهد شد. تنها در صورتی که سرور iframe Reporting-Endpoints را تنظیم کرده باشد، گزارش منسوخ ایجاد می‌شود و این گزارش به هر نقطه پایانی که سرور 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 of 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"

اگر از 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 را تعریف نکرده باشد، گزارش‌هایی از این نوع ارسال نمی‌شوند (اگرچه ایجاد می‌شوند).

نکته کلیدی: با وجود نام آن، default یک نقطه پایانی بازگشتی نیست . به عنوان مثال، اگر report-to my-endpoint برای Document-Policy تنظیم کنید و تعریف my-endpoint در Reporting-Endpoints حذف کنید، گزارش‌های نقض Document-Policy ایجاد می‌شود اما ارسال نمی‌شود زیرا مرورگر نمی‌داند کجاست. برای ارسال آنها به.

مقادیر (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();
});

توجه: این با API گزارش‌دهی قدیمی (سرصفحه Report-To ) متفاوت است، جایی که می‌توانید یک نقطه پایانی «محیطی» را برای یک صفحه تنظیم کنید و به‌طور خودکار برای هر صفحه در همان مبدا گزارش دریافت کنید. اگر از API قدیمی Reporting به API گزارش‌گیری جدید مهاجرت می‌کنید، راهنمای انتقال را بررسی کنید.

خط مشی های خود را ویرایش کنید

اکنون که سرصفحه 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

اخطار: درست کردن دستور report-to به نحو ممکن است مشکل باشد، زیرا همه خط‌مشی‌ها از ساختار سرصفحه یکسانی استفاده نمی‌کنند. بسته به خط مشی، نحو مناسب ممکن است report-to=main-endpoint یا report-to main-endpoint باشد. برای نمونه کد به نسخه ی نمایشی بروید.

کد نمونه

برای مشاهده همه اینها در زمینه، در زیر نمونه ای از سرور Node است که از Express استفاده می کند و تمام قطعات مورد بحث در این مقاله را گرد هم می آورد. نحوه پیکربندی گزارش برای چندین نوع گزارش مختلف را نشان می دهد و نتایج را نمایش می دهد.

تنظیمات گزارش خود را اشکال زدایی کنید

به طور عمدی گزارش تولید کنید

هنگام تنظیم API Reporting، احتمالاً باید عمداً خط‌مشی‌های خود را نقض کنید تا بررسی کنید که آیا گزارش‌ها مطابق انتظار تولید و ارسال می‌شوند یا خیر. برای مشاهده نمونه کدی که خط‌مشی‌ها را نقض می‌کند و کارهای بد دیگری را انجام می‌دهد که انواع گزارش‌ها را تولید می‌کند، نسخه آزمایشی را بررسی کنید.

صرفه جویی در زمان

گزارش‌ها ممکن است با تأخیر ارسال شوند - حدود یک دقیقه، که در هنگام اشکال‌زدایی زمان طولانی است. 😴 خوشبختانه، هنگام اشکال زدایی در کروم، می توانید از پرچم --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 فهرست می‌شود.

اسکرین شات DevTools که گزارش ها را فهرست می کند — Chrome DevTools گزارش های تولید شده در صفحه شما و وضعیت آنها را نمایش می دهد.

گزارش وضعیت

ستون وضعیت به شما می گوید که آیا گزارشی با موفقیت ارسال شده است یا خیر.

وضعیت	شرح
`Success`	مرورگر گزارش را ارسال کرده است و نقطه پایانی با یک کد موفقیت پاسخ داده است ( `200` یا کد پاسخ موفقیت آمیز دیگری `2xx` ).
`Pending`	مرورگر در حال حاضر در حال تلاش برای ارسال گزارش است.
`Queued`	گزارش ایجاد شده است و مرورگر در حال حاضر سعی در ارسال آن ندارد. یک گزارش در یکی از این دو مورد به صورت `Queued` ظاهر می شود: گزارش جدید است و مرورگر منتظر است تا قبل از ارسال آن گزارش‌های بیشتری دریافت کند یا خیر. گزارش جدید نیست. مرورگر قبلاً سعی کرده است این گزارش را ارسال کند و شکست خورده است و قبل از تلاش مجدد منتظر است.
`MarkedForRemoval`	پس از مدتی تلاش مجدد ( `Queued` )، مرورگر تلاش برای ارسال گزارش را متوقف کرده و به زودی آن را از لیست گزارش های ارسالی خود حذف خواهد کرد.

گزارش‌ها پس از مدتی حذف می‌شوند، چه با موفقیت ارسال شوند یا نه.

نکته کلیدی: وضعیت Queued همیشه آموزنده نیست، زیرا دقیقاً نشان نمی دهد که آیا ارسال ناموفق بوده یا هنوز تلاشی نشده است. استفاده از تأخیرهای کوتاه گزارش کمک می کند: گزارشی که در آن حالت Queued باقی می ماند احتمالاً نشان می دهد که ارسال ناموفق است.

عیب یابی

آیا گزارش ها همانطور که انتظار می رود به نقطه پایانی شما ارسال نمی شود یا تولید نمی شود؟ در اینجا چند نکته برای رفع این مشکل وجود دارد.

گزارش ایجاد نمی شود

گزارش هایی که در DevTools نشان داده می شوند به درستی تولید شده اند. اگر گزارش مورد انتظار شما در این لیست نمایش داده نمی شود:

report-to در خط‌مشی‌های خود بررسی کنید. اگر این پیکربندی اشتباه باشد، گزارشی ایجاد نخواهد شد. برای رفع این مشکل، به ویرایش خط‌مشی‌های خود بروید. یک راه دیگر برای عیب‌یابی این است که کنسول DevTools در کروم را بررسی کنید: اگر خطایی در کنسول برای نقض مورد انتظار شما ظاهر شد، به این معنی است که خط‌مشی شما احتمالاً به درستی پیکربندی شده است.
به خاطر داشته باشید که فقط گزارش‌هایی که برای سندی که DevTools در آن باز است ایجاد شده‌اند در این لیست نشان داده می‌شوند. یک مثال: اگر سایت شما site1.example یک iframe site2.example را تعبیه کند که یک خط مشی را نقض می کند و در نتیجه گزارشی تولید می کند، این گزارش تنها در صورتی در DevTools نشان داده می شود که iframe را در پنجره خودش باز کنید و DevTools را برای آن پنجره باز کنید.

گزارش ها تولید می شوند اما ارسال نمی شوند یا دریافت نمی شوند

اگر بتوانید گزارشی را در DevTools ببینید، اما نقطه پایانی شما آن را دریافت نکند، چه؟

نکته کلیدی: از آنجایی که گزارش خارج از باند توسط خود مرورگر ارسال می‌شود و نه توسط سایت خاصی، درخواست‌های POST حاوی گزارش‌ها در پنل Network Developer Tools شما نمایش داده نمی‌شوند.

حتما از تاخیرهای کوتاه استفاده کنید. شاید دلیل اینکه گزارشی را نمی بینید این باشد که هنوز ارسال نشده است!
پیکربندی سرصفحه Reporting-Endpoints خود را بررسی کنید. اگر مشکلی در آن وجود داشته باشد، گزارشی که به درستی ایجاد شده باشد ارسال نخواهد شد. در DevTools، وضعیت گزارش 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 خط‌مشی‌ها را اجرا نمی‌کنند: هیچ چیز خراب نمی‌شود یا در واقع مسدود نمی‌شود، اما گزارش‌هایی از مواردی که شکسته یا مسدود شده‌اند دریافت خواهید کرد.

توجه: اگر از سرصفحه -Report-Only استفاده می کنید و نقاط پایانی گزارش خود را از طریق هدر قدیمی Report-To پیکربندی کرده اید، در صورت امکان به Reporting-Endpoints منتقل کنید. در راهنمای مهاجرت بیشتر بخوانید.

`ReportingObserver`

ReportingObserver JavaScript API می تواند به شما کمک کند تا هشدارهای سمت سرویس گیرنده را مشاهده کنید.

ReportingObserver و هدر Reporting-Endpoints گزارش هایی را تولید می کنند که ظاهر یکسانی دارند، اما موارد استفاده کمی متفاوت را فعال می کنند.

اگر از ReportingObserver استفاده کنید:

شما فقط می‌خواهید موارد منسوخ شده و/یا مداخلات مرورگر را نظارت کنید. ReportingObserver اخطارهای سمت سرویس گیرنده مانند لغو و مداخلات مرورگر را نشان می دهد، اما برخلاف Reporting-Endpoints ، هیچ نوع گزارش دیگری مانند نقض CSP یا COOP/COEP را ثبت نمی کند.
شما باید در زمان واقعی به این تخلفات واکنش نشان دهید. ReportingObserver این امکان را فراهم می کند که یک تماس برگشتی را به یک رویداد نقض پیوست کنید .
می‌خواهید اطلاعات بیشتری را از طریق پاسخ به تماس سفارشی به یک گزارش پیوست کنید تا به اشکال‌زدایی کمک کنید.

تفاوت دیگر این است که ReportingObserver فقط در سمت کلاینت پیکربندی شده است: حتی اگر کنترلی روی هدر سمت سرور ندارید و نمی توانید Reporting-Endpoints تنظیم کنید، می توانید از آن استفاده کنید.

بیشتر خواندن

تصویر قهرمان توسط Nine Koepfer / @enka80 در Unsplash ، ویرایش شده است. با تشکر فراوان از ایان کللند، ایجی کیتامورا و میلیکا میهایلیجا برای نظرات و پیشنهاداتشان در مورد این مقاله.