مهاجرت به Reporting API v1

نسخه جدیدی از Reporting API در دسترس است. خصوصی تر است و به احتمال زیاد در مرورگرها پشتیبانی می شود.

مود نالپاس
Maud Nalpas
X GitHub

گزارش API شما را در مورد خطاهایی که در سایت شما هنگام استفاده بازدیدکنندگان از آن رخ می دهد، آگاه می کند. این به شما امکان مشاهده مداخلات مرورگر، خرابی مرورگر، نقض خط‌مشی محتوا-امنیت، نقض COOP/COEP، هشدارهای منسوخ شدن و موارد دیگر را می‌دهد.

نسخه جدیدی از Reporting API در دسترس است. API جدید کمتر است و به احتمال زیاد در مرورگرها پشتیبانی می شود.

خلاصه

توسعه دهندگان سایت

اگر از قبل قابلیت گزارش دهی برای سایت خود دارید : با استفاده از هدر جدید ( Reporting-Endpoints ) به نسخه 1 مهاجرت کنید، اما هدر قدیمی را برای مدتی نگه دارید ( Report-To ). به مهاجرت مراجعه کنید: کد نمونه .

اگر همین الان در حال اضافه کردن عملکرد گزارش به سایت خود هستید : فقط از سربرگ جدید ( Reporting-Endpoints ) استفاده کنید.

⚠️ در هر دو مورد، مطمئن شوید که هدر Reporting-Endpoints را روی همه پاسخ هایی که ممکن است گزارش ایجاد کنند، تنظیم کنید.

توسعه دهندگان خدمات گزارش

اگر یک سرویس نقطه پایانی را حفظ می کنید یا خدمات خود را اجرا می کنید، با مهاجرت شما یا توسعه دهندگان خارجی به Reporting API v1 (سرصفحه Reporting-Endpoints ) انتظار ترافیک بیشتری را داشته باشید.

برای جزئیات و کد نمونه به خواندن ادامه دهید!

ثبت خطای شبکه

مکانیزم جدیدی برای ثبت خطاهای شبکه ایجاد خواهد شد. پس از در دسترس قرار گرفتن، از Reporting API v0 به مکانیسم جدید تغییر دهید.

نسخه ی نمایشی و کد

تفاوت بین v0 و v1

چه چیزی در حال تغییر است

  • سطح API متفاوت است.
v0 (میراث) 
 Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }
 Document-Policy: ...; report-to main-endpoint

{0 از سرصفحه Report-To برای پیکربندی گروه‌های نقطه پایانی نام‌گذاری‌شده و دستورالعمل report-to در سرصفحه‌های دیگر برای ارجاع به این گروه‌های نقطه پایانی استفاده می‌کند.

v1 (جدید) 
 Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
 Document-Policy: ...; report-to main-endpoint

v1 از هدر Reporting-Endpoints برای پیکربندی نقاط انتهایی نامگذاری شده استفاده می کند. مانند v0، از دستورالعمل report-to به در سرفصل های دیگر برای ارجاع به این گروه های نقطه پایانی استفاده می کند.

  • دامنه گزارش متفاوت است.
v0 (میراث)

با v0، می‌توانید نقاط پایانی گزارش را فقط برای برخی از پاسخ‌ها تنظیم کنید. سایر اسناد (صفحات) در آن مبدا به طور خودکار از این نقاط پایانی محیطی استفاده می کنند.

v1 (جدید)

با v1، باید سرصفحه Reporting-Endpoints را روی تمام پاسخ هایی که ممکن است گزارش ایجاد کنند، تنظیم کنید.

  • هر دو API از یک نوع گزارش پشتیبانی می‌کنند، با یک استثنا: v1 از گزارش‌های خطای شبکه پشتیبانی نمی‌کند. در مراحل مهاجرت بیشتر بخوانید.
  • v0 در مرورگرها پشتیبانی نمی شود و نخواهد بود. v1 به احتمال زیاد در آینده در چندین مرورگر پشتیبانی می شود.

چیزی که بدون تغییر باقی می ماند

  • قالب و ساختار گزارش ها بدون تغییر است.
  • درخواست ارسال شده توسط مرورگر به نقطه پایانی یک درخواست POST از Content-type application/reports+json باقی می ماند.
  • نگاشت نقاط پایانی خاص به انواع گزارش های خاص در هر دو نسخه v0 و v1 پشتیبانی می شود.
  • نقش نقطه پایانی default بدون تغییر است.

  • Reporting API v1 هیچ تاثیری بر ReportingObserver ندارد. ReportingObserver همچنان به همه گزارش های قابل مشاهده دسترسی پیدا می کند و قالب آنها یکسان است.

تمام تفاوت های بین v0 و v1

API گزارش قدیمی (نسخه 0)
Report-To سربرگ		 API گزارش جدید (نسخه 1)
هدر Reporting-Endpoints
پشتیبانی از مرورگر Chrome 69+ و Edge 69+. Chrome 96+ و Edge 96+. فایرفاکس پشتیبانی می کند. سافاری مخالفتی ندارد. سیگنال های مرورگر را ببینید.
نقاط پایانی گزارش‌ها را به هر یک از چندین گردآورنده گزارش ارسال می‌کند (چند URL تعریف شده در هر گروه نقطه پایانی). گزارش‌ها را به جمع‌آوران گزارش خاص ارسال می‌کند (فقط یک URL در هر نقطه پایانی تعریف شده است).
سطح API از هدر `Report-To` برای پیکربندی گروه‌های نقطه پایانی نام‌گذاری شده استفاده می‌کند. از سرصفحه `Reporting-Endpoints` برای پیکربندی نقاط انتهایی نام‌گذاری شده استفاده می‌کند.
انواع گزارشی که می توان از طریق این API ایجاد کرد
  • منسوخ شدن
  • مداخله
  • سقوط
  • COOP/COEP
  • Content-Security-Policy Level 3 (CSP Level 3)
  • ثبت خطای شبکه (NEL)
در پست Reporting API درباره انواع گزارش بیشتر بیاموزید.		 بدون تغییر، به جز گزارش خطای شبکه (NEL): این مورد در گزارش API جدید (v1) پشتیبانی نمی‌شود .
دامنه گزارش مبدا.
سرصفحه Report-To یک سند روی سایر اسناد (صفحات) از آن مبدا تأثیر می گذارد. فیلد url گزارش همچنان در هر سند متفاوت است.		 سند.
هدر Reporting-Endpoints یک سند فقط روی آن سند تأثیر می گذارد. فیلد url گزارش همچنان در هر سند متفاوت است.
گزارش جداسازی (بچینگ) اسناد (صفحات) یا سایت‌ها/منشأهای مختلف که گزارشی را تقریباً در یک زمان تولید می‌کنند و نقطه پایانی گزارش یکسانی دارند با هم جمع می‌شوند: آنها در یک پیام به نقطه پایانی گزارش ارسال می‌شوند.
  • گزارش های اسناد (صفحات) مختلف هرگز با هم ارسال نمی شوند. حتی اگر دو سند (صفحه) از یک مبدأ به طور همزمان گزارشی برای یک نقطه پایانی ایجاد کنند، اینها دسته بندی نمی شوند. این مکانیسمی برای کاهش حملات حریم خصوصی است.
  • ممکن است گزارش ها از همان سند (صفحه) با هم ارسال شوند.
پشتیبانی از تعادل بار / اولویت ها بله خیر

توسعه دهندگان نقطه پایانی: انتظار ترافیک بیشتری داشته باشید

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

این به این دلیل است که گزارش‌ها با Reporting API v1 مانند Reporting API v0 دسته‌بندی نمی‌شوند. بنابراین، با شروع مهاجرت توسعه دهندگان برنامه به Reporting API v1، تعداد گزارش ها مشابه باقی می ماند، اما حجم درخواست ها به سرور نقطه پایانی افزایش می یابد.

توسعه دهندگان برنامه: مهاجرت به Reporting-Endpoints (v1)

چه کاری باید انجام دهید؟

استفاده از Reporting API جدید (v1) چندین مزیت دارد:

  • سیگنال‌های مرورگر مثبت هستند، به این معنی که برای نسخه 1 می‌توان از بین مرورگرها پشتیبانی کرد (برخلاف نسخه 0 که فقط در کروم و اج پشتیبانی می‌شود).
  • API لاغرتر است.
  • Tooling حول API جدید Reporting (v1) در حال توسعه است.

با این حساب:

  • اگر سایت شما قبلاً از Reporting API v0 با هدر Report-To استفاده می‌کند، به Reporting API v1 بروید ( مراحل انتقال را ببینید). اگر سایت شما قبلاً از عملکرد گزارش برای نقض سیاست محتوا-امنیت-استفاده می‌کند، مراحل انتقال خاص برای گزارش CSP را بررسی کنید.
  • اگر سایت شما قبلاً از Reporting API استفاده نمی‌کند و اکنون عملکرد گزارش را اضافه می‌کنید: از Reporting API جدید (v1) (هدر Reporting-Endpoints ) استفاده کنید. یک استثنا برای این وجود دارد : اگر نیاز به استفاده از گزارش خطای شبکه دارید، از Report-To (v0) استفاده کنید. ثبت خطای شبکه در حال حاضر در Reporting API v1 پشتیبانی نمی‌شود. مکانیزم جدیدی برای ثبت خطاهای شبکه ایجاد خواهد شد⏤تا زمانی که در دسترس باشد، از Reporting API v0 استفاده کنید. اگر به ثبت خطاهای شبکه در کنار انواع دیگر گزارش نیاز دارید، از Report-To (v0) و Reporting-Endpoints (v1) استفاده کنید. v0 به شما گزارش خطای شبکه و v1 گزارش انواع دیگر را به شما می دهد.

مراحل مهاجرت

هدف شما در این مهاجرت این است که گزارش هایی را که قبلاً با v0 دریافت می کردید از دست ندهید .

  1. مرحله 1 (اکنون انجام دهید) : از هر دو عنوان استفاده کنید: Report-To (v0) و Reporting-Endpoints (v1).

    با این، شما دریافت می کنید:

    • گزارش‌های مشتریان جدیدتر Chrome و Edge به لطف Reporting-Endpoints (v1).
    • گزارش‌های مشتریان قدیمی Chrome و Edge به لطف Report-To (v0).

    نمونه‌های مرورگری که از Reporting-Endpoints پشتیبانی می‌کنند Reporting-Endpoints استفاده می‌کنند و نمونه‌هایی که از آن پشتیبانی نمی‌کنند به Report-To بازگشت می‌دهند. فرمت درخواست و گزارش برای v0 و v1 یکسان است.

  2. مرحله 2 (اکنون انجام دهید): اطمینان حاصل کنید که هدر Reporting-Endpoints روی همه پاسخ هایی که ممکن است گزارش ایجاد کنند تنظیم شده باشد.

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

  3. مرحله 3 (زمان شروع): هنگامی که همه یا بیشتر کاربران شما به نصب های بعدی Chrome یا Edge (96 و بالاتر) به روز شدند، Report-To (v0) را حذف کنید و فقط Reporting-Endpoints نگه دارید.

    یک استثنا: اگر به گزارش‌های ثبت خطای شبکه نیاز دارید، Report-To نگه دارید تا مکانیزم جدیدی برای ثبت خطاهای شبکه ایجاد شود.

نمونه کد را در کتاب آشپزی مهاجرت ببینید.

مراحل مهاجرت برای گزارش CSP

به دو روش می‌توان گزارش‌های نقض Content-Security-Policy را پیکربندی کرد:

  • تنها با هدر CSP از طریق دستورالعمل report-uri . این از مرورگر گسترده ای در کروم، فایرفاکس، سافاری و اج پشتیبانی می کند. گزارش‌ها با application/csp-report نوع محتوا ارسال می‌شوند و فرمتی دارند که مختص CSP است. این گزارش ها "گزارش های سطح 2 CSP" نامیده می شوند و به گزارش API متکی نیستند .
  • با گزارش API، از طریق هدر Report-To (میراث) یا Reporting-Endpoints جدیدتر (v1). این فقط در Chrome و Edge پشتیبانی می‌شود. فرمت درخواست‌های گزارش مانند سایر درخواست‌های Reporting API و همان نوع محتوا application/reports+json است.

استفاده از رویکرد اول (فقط report-uri ) دیگر توصیه نمی شود و استفاده از رویکرد دوم مزایای کمی دارد. به طور خاص، به شما امکان می‌دهد از یک راه واحد برای تنظیم گزارش برای همه انواع گزارش و همچنین تنظیم یک نقطه پایانی عمومی استفاده کنید (زیرا همه درخواست‌های گزارش ایجاد شده از طریق Reporting API⏤CSP و موارد دیگر⏤با فرمت یکسان application/reports+json هستند. application/reports+json

با این حال، فقط تعداد کمی از مرورگرها report-to پشتیبانی می کنند . بنابراین توصیه می‌شود report-uri در کنار رویکرد Reporting API ( Report-To یا بهتر، Reporting-Endpoints ) نگه دارید تا گزارش‌های نقض CSP را از چندین مرورگر دریافت کنید. در مرورگری که report-uri و report-to تشخیص می دهد، در صورت وجود report-to report-uri نادیده گرفته می شود. در مرورگری که فقط report-uri می شناسد، فقط report-uri در نظر گرفته می شود.

  1. مرحله 1 (اکنون انجام دهید) : اگر هنوز آن را اضافه نکرده اید، report-to در کنار report-uri اضافه کنید. مرورگرهایی که فقط report-uri (Firefox) پشتیبانی می‌کنند، report-uri استفاده می‌کنند و مرورگرهایی که report-to (Chrome، Edge) نیز پشتیبانی می‌کنند، report-to استفاده می‌کنند. برای مشخص کردن نقاط پایانی نام‌گذاری شده‌ای که در report-to استفاده می‌کنید، از هر دو سرصفحه Report-To و Reporting-Endpoints استفاده کنید. این تضمین می‌کند که گزارش‌هایی را از مشتریان قدیمی‌تر و جدیدتر Chrome و Edge دریافت می‌کنید.

  2. مرحله 3 (زمان شروع): هنگامی که همه یا بیشتر کاربران شما به نصب های بعدی Chrome یا Edge (96 و بالاتر) به روز شدند، Report-To (v0) را حذف کنید و فقط Reporting-Endpoints نگه دارید. report-uri نگه دارید تا همچنان گزارش هایی برای مرورگرهایی که فقط از آن پشتیبانی می کنند دریافت کنید.

نمونه کد این مراحل را در انتقال گزارش CSP ببینید.

مهاجرت: کد نمونه

نمای کلی

اگر از API گزارش‌دهی قدیمی (v0) برای دریافت گزارش‌های نقض برای aa COOP (سرصفحه Cross-Origin-Opener-Policy )، COEP ( Cross-Origin-Embedder-Policy ) یا خط‌مشی سند (سرصفحه Document-Policy ) استفاده می‌کنید. ): با انتقال به Reporting API v1، نیازی به تغییر این سرصفحه های خط مشی ندارید. آنچه شما نیاز دارید این است که از هدر قدیمی Report-To به سربرگ جدید Reporting-Endpoints مهاجرت کنید.

اگر از API قدیمی Reporting (v0) برای دریافت گزارش تخلف برای یک CSP (سربرگ Content-Security-Policy ) استفاده می کنید، ممکن است لازم باشد Content-Security-Policy خود را به عنوان بخشی از انتقال خود به API گزارش جدید تغییر دهید ( v1).

مهاجرت اساسی

کد قدیمی (با v0) 
Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }
کد جدید (کد انتقال با v0 در کنار v1) 
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/default" }] }

اگر از قبل قابلیت گزارش دهی در سایت خود دارید، Report-To فقط به طور موقت نگه دارید (تا زمانی که اکثر کلاینت های Chrome و Edge به روز شوند) تا از دست دادن گزارش ها جلوگیری کنید.

اگر به گزارش خطای شبکه نیاز دارید، Report-To نگه دارید تا زمانی که جایگزینی گزارش خطای شبکه در دسترس قرار گیرد .

کد جدید (فقط با v1) 
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

زمانی که اکثر کلاینت‌های Chrome و Edge به‌روزرسانی شوند و از API v1 پشتیبانی کنند، کد شما در آینده می‌تواند به این شکل باشد.

توجه داشته باشید که با v1، همچنان می‌توانید انواع گزارش‌های خاص را به نقاط پایانی خاص ارسال کنید. اما شما می توانید تنها یک URL در هر نقطه پایانی داشته باشید.

مشاهده تمامی صفحات

کد قدیمی (با v0)، به عنوان مثال با Express 
app.get("/", (request, response) => {
  response.set("Report-To", …)
  response.render(...)
});
app.get("/page1", (request, response) => {
  response.render(...)
});

با v0، می‌توانید نقاط پایانی گزارش را فقط برای برخی از پاسخ‌ها تنظیم کنید. سایر اسناد (صفحات) در آن مبدا به طور خودکار از این نقاط پایانی محیطی استفاده می کنند. در اینجا، نقاط پایانی تنظیم شده برای "/" برای همه پاسخ ها، به عنوان مثال برای page1 استفاده می شود.

کد جدید (با v1)، به عنوان مثال با Express 
// Use a middleware to set the reporting endpoint(s) for *all* requests.
app.use(function(request, response, next) {
  response.set("Reporting-Endpoints", …);
  next();
});

app.get("/", (request, response) => {
  response.render(...)
});

app.get("/page1", (request, response) => {
  response.render(...)
});

با v1، باید سرصفحه Reporting-Endpoints را روی تمام پاسخ هایی که ممکن است گزارش ایجاد کنند، تنظیم کنید.

مهاجرت گزارش CSP

کد قدیمی، فقط با گزارش-uri 
Content-Security-Policy: ...; report-uri https://reports.example/main

استفاده از report-uri دیگر توصیه نمی شود . اگر کد شما مانند بالا است، مهاجرت کنید. نمونه های کد جدید را در زیر ببینید (به رنگ سبز).

کد قدیمی بهتر، با گزارش-uri و دستورالعمل گزارش به با هدر Report-To (v0) 
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Report-To: main-endpoint="https://reports.example/main"

این بهتر است: این کد از report-to استفاده می کند که جایگزین جدیدتر برای report-uri است. همچنان گزارش-uri را برای سازگاری با عقب نگه می دارد. چندین مرورگر report-to پشتیبانی نمی کنند اما از report-uri پشتیبانی می کنند.

با این حال، این می تواند بهتر باشد: این کدها از Reporting API v0 (هدر Report-To ) استفاده می کنند. مهاجرت به نسخه 1: نمونه های "کد جدید" را در زیر ببینید (به رنگ سبز).

کد جدید، با گزارش-uri و دستورالعمل گزارش به با سربرگ Reporting-Endpoints (v1) 
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Reporting-Endpoints: main-endpoint="https://reports.example/main"
Report-To: ...

دستورالعمل report-uri را در کنار report-to دستورالعمل نگه دارید تا زمانی که دستورالعمل report-to در مرورگرها پشتیبانی شود. جدول سازگاری مرورگر را ببینید.

به طور موقت Report-To در کنار Reporting-Endpoints نگه دارید. هنگامی که اکثر بازدیدکنندگان Chrome و Edge شما به بیش از ۹۶ نسخه مرورگر ارتقا یافتند، Report-To را حذف کنید.

در ادامه مطلب

با تشکر فراوان از Ian Clelland، Eiji Kitamura و Milica Mihajlija برای نظرات و پیشنهاداتشان در مورد این مقاله.

،

نسخه جدیدی از Reporting API در دسترس است. خصوصی تر است و به احتمال زیاد در مرورگرها پشتیبانی می شود.

مود نالپاس
Maud Nalpas
X GitHub

گزارش API شما را در مورد خطاهایی که در سایت شما هنگام استفاده بازدیدکنندگان از آن رخ می دهد، آگاه می کند. این به شما امکان مشاهده مداخلات مرورگر، خرابی مرورگر، نقض خط‌مشی محتوا-امنیت، نقض COOP/COEP، هشدارهای منسوخ شدن و موارد دیگر را می‌دهد.

نسخه جدیدی از Reporting API در دسترس است. API جدید کمتر است و به احتمال زیاد در مرورگرها پشتیبانی می شود.

خلاصه

توسعه دهندگان سایت

اگر از قبل قابلیت گزارش دهی برای سایت خود دارید : با استفاده از هدر جدید ( Reporting-Endpoints ) به نسخه 1 مهاجرت کنید، اما هدر قدیمی را برای مدتی نگه دارید ( Report-To ). به مهاجرت مراجعه کنید: کد نمونه .

اگر همین الان در حال اضافه کردن عملکرد گزارش به سایت خود هستید : فقط از سربرگ جدید ( Reporting-Endpoints ) استفاده کنید.

⚠️ در هر دو مورد، مطمئن شوید که هدر Reporting-Endpoints را روی همه پاسخ هایی که ممکن است گزارش ایجاد کنند، تنظیم کنید.

توسعه دهندگان خدمات گزارش

اگر یک سرویس نقطه پایانی را حفظ می کنید یا خدمات خود را اجرا می کنید، با مهاجرت شما یا توسعه دهندگان خارجی به Reporting API v1 (سرصفحه Reporting-Endpoints ) انتظار ترافیک بیشتری را داشته باشید.

برای جزئیات و کد نمونه به خواندن ادامه دهید!

ثبت خطای شبکه

مکانیزم جدیدی برای ثبت خطاهای شبکه ایجاد خواهد شد. پس از در دسترس قرار گرفتن، از Reporting API v0 به مکانیسم جدید تغییر دهید.

نسخه ی نمایشی و کد

تفاوت بین v0 و v1

چه چیزی در حال تغییر است

  • سطح API متفاوت است.
v0 (میراث) 
 Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }
 Document-Policy: ...; report-to main-endpoint

{0 از سرصفحه Report-To برای پیکربندی گروه‌های نقطه پایانی نام‌گذاری‌شده و دستورالعمل report-to در سرصفحه‌های دیگر برای ارجاع به این گروه‌های نقطه پایانی استفاده می‌کند.

v1 (جدید) 
 Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
 Document-Policy: ...; report-to main-endpoint

v1 از هدر Reporting-Endpoints برای پیکربندی نقاط انتهایی نامگذاری شده استفاده می کند. مانند v0، از دستورالعمل report-to به در سرفصل های دیگر برای ارجاع به این گروه های نقطه پایانی استفاده می کند.

  • دامنه گزارش متفاوت است.
v0 (میراث)

با v0، می‌توانید نقاط پایانی گزارش را فقط برای برخی از پاسخ‌ها تنظیم کنید. سایر اسناد (صفحات) در آن مبدا به طور خودکار از این نقاط پایانی محیطی استفاده می کنند.

v1 (جدید)

با v1، باید سرصفحه Reporting-Endpoints را روی تمام پاسخ هایی که ممکن است گزارش ایجاد کنند، تنظیم کنید.

  • هر دو API از یک نوع گزارش پشتیبانی می‌کنند، با یک استثنا: v1 از گزارش‌های خطای شبکه پشتیبانی نمی‌کند. در مراحل مهاجرت بیشتر بخوانید.
  • v0 در مرورگرها پشتیبانی نمی شود و نخواهد بود. v1 به احتمال زیاد در آینده در چندین مرورگر پشتیبانی می شود.

چیزی که بدون تغییر باقی می ماند

  • قالب و ساختار گزارش ها بدون تغییر است.
  • درخواست ارسال شده توسط مرورگر به نقطه پایانی یک درخواست POST از Content-type application/reports+json باقی می ماند.
  • نگاشت نقاط پایانی خاص به انواع گزارش های خاص در هر دو نسخه v0 و v1 پشتیبانی می شود.
  • نقش نقطه پایانی default بدون تغییر است.

  • Reporting API v1 هیچ تاثیری بر ReportingObserver ندارد. ReportingObserver همچنان به همه گزارش های قابل مشاهده دسترسی پیدا می کند و قالب آنها یکسان است.

تمام تفاوت های بین v0 و v1

API گزارش قدیمی (نسخه 0)
Report-To سربرگ		 API گزارش جدید (نسخه 1)
هدر Reporting-Endpoints
پشتیبانی از مرورگر Chrome 69+ و Edge 69+. Chrome 96+ و Edge 96+. فایرفاکس پشتیبانی می کند. سافاری مخالفتی ندارد. سیگنال های مرورگر را ببینید.
نقاط پایانی گزارش‌ها را به هر یک از چندین گردآورنده گزارش ارسال می‌کند (چند URL تعریف شده در هر گروه نقطه پایانی). گزارش‌ها را به جمع‌آوران گزارش خاص ارسال می‌کند (فقط یک URL در هر نقطه پایانی تعریف شده است).
سطح API از هدر `Report-To` برای پیکربندی گروه‌های نقطه پایانی نام‌گذاری شده استفاده می‌کند. از سرصفحه `Reporting-Endpoints` برای پیکربندی نقاط انتهایی نام‌گذاری شده استفاده می‌کند.
انواع گزارشی که می توان از طریق این API ایجاد کرد
  • منسوخ شدن
  • مداخله
  • سقوط
  • COOP/COEP
  • Content-Security-Policy Level 3 (CSP Level 3)
  • ثبت خطای شبکه (NEL)
در پست Reporting API درباره انواع گزارش بیشتر بیاموزید.		 بدون تغییر، به جز گزارش خطای شبکه (NEL): این مورد در گزارش API جدید (v1) پشتیبانی نمی‌شود .
دامنه گزارش مبدا.
سرصفحه Report-To یک سند روی سایر اسناد (صفحات) از آن مبدا تأثیر می گذارد. فیلد url گزارش همچنان در هر سند متفاوت است.		 سند.
هدر Reporting-Endpoints یک سند فقط روی آن سند تأثیر می گذارد. فیلد url گزارش همچنان در هر سند متفاوت است.
گزارش جداسازی (بچینگ) اسناد (صفحات) یا سایت‌ها/منشأهای مختلف که گزارشی را تقریباً در یک زمان تولید می‌کنند و نقطه پایانی گزارش یکسانی دارند با هم جمع می‌شوند: آنها در یک پیام به نقطه پایانی گزارش ارسال می‌شوند.
  • گزارش های اسناد (صفحات) مختلف هرگز با هم ارسال نمی شوند. حتی اگر دو سند (صفحه) از یک مبدأ به طور همزمان گزارشی برای یک نقطه پایانی ایجاد کنند، اینها دسته بندی نمی شوند. این مکانیسمی برای کاهش حملات حریم خصوصی است.
  • ممکن است گزارش ها از همان سند (صفحه) با هم ارسال شوند.
پشتیبانی از تعادل بار / اولویت ها بله خیر

توسعه دهندگان نقطه پایانی: انتظار ترافیک بیشتری داشته باشید

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

این به این دلیل است که گزارش‌ها با Reporting API v1 مانند Reporting API v0 دسته‌بندی نمی‌شوند. بنابراین، با شروع مهاجرت توسعه دهندگان برنامه به Reporting API v1، تعداد گزارش ها مشابه باقی می ماند، اما حجم درخواست ها به سرور نقطه پایانی افزایش می یابد.

توسعه دهندگان برنامه: مهاجرت به Reporting-Endpoints (v1)

چه کاری باید انجام دهید؟

استفاده از Reporting API جدید (v1) چندین مزیت دارد:

  • سیگنال‌های مرورگر مثبت هستند، به این معنی که برای نسخه 1 می‌توان از بین مرورگرها پشتیبانی کرد (برخلاف نسخه 0 که فقط در کروم و اج پشتیبانی می‌شود).
  • API لاغرتر است.
  • Tooling حول API جدید Reporting (v1) در حال توسعه است.

با این حساب:

  • اگر سایت شما قبلاً از Reporting API v0 با هدر Report-To استفاده می‌کند، به Reporting API v1 بروید ( مراحل انتقال را ببینید). اگر سایت شما قبلاً از عملکرد گزارش برای نقض سیاست محتوا-امنیت-استفاده می‌کند، مراحل انتقال خاص برای گزارش CSP را بررسی کنید.
  • اگر سایت شما قبلاً از Reporting API استفاده نمی‌کند و اکنون عملکرد گزارش را اضافه می‌کنید: از Reporting API جدید (v1) (هدر Reporting-Endpoints ) استفاده کنید. یک استثنا برای این وجود دارد : اگر نیاز به استفاده از گزارش خطای شبکه دارید، از Report-To (v0) استفاده کنید. ثبت خطای شبکه در حال حاضر در Reporting API v1 پشتیبانی نمی‌شود. مکانیزم جدیدی برای ثبت خطاهای شبکه ایجاد خواهد شد⏤تا زمانی که در دسترس باشد، از Reporting API v0 استفاده کنید. اگر به ثبت خطاهای شبکه در کنار انواع دیگر گزارش نیاز دارید، از Report-To (v0) و Reporting-Endpoints (v1) استفاده کنید. v0 به شما گزارش خطای شبکه و v1 گزارش انواع دیگر را به شما می دهد.

مراحل مهاجرت

هدف شما در این مهاجرت این است که گزارش هایی را که قبلاً با v0 دریافت می کردید از دست ندهید .

  1. مرحله 1 (اکنون انجام دهید) : از هر دو عنوان استفاده کنید: Report-To (v0) و Reporting-Endpoints (v1).

    با این، شما دریافت می کنید:

    • گزارش‌های مشتریان جدیدتر Chrome و Edge به لطف Reporting-Endpoints (v1).
    • گزارش‌های مشتریان قدیمی Chrome و Edge به لطف Report-To (v0).

    نمونه‌های مرورگری که از Reporting-Endpoints پشتیبانی می‌کنند، Reporting-Endpoints استفاده می‌کنند و نمونه‌هایی که از آن پشتیبانی نمی‌کنند به Report-To بازگشت می‌دهند. فرمت درخواست و گزارش برای v0 و v1 یکسان است.

  2. مرحله 2 (اکنون انجام دهید): اطمینان حاصل کنید که هدر Reporting-Endpoints روی همه پاسخ هایی که ممکن است گزارش ایجاد کنند تنظیم شده باشد.

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

  3. مرحله 3 (زمان شروع): هنگامی که همه یا بیشتر کاربران شما به نصب های بعدی Chrome یا Edge (96 و بالاتر) به روز شدند، Report-To (v0) را حذف کنید و فقط Reporting-Endpoints نگه دارید.

    یک استثنا: اگر به گزارش‌های ثبت خطای شبکه نیاز دارید، Report-To نگه دارید تا مکانیزم جدیدی برای ثبت خطاهای شبکه ایجاد شود.

نمونه کد را در کتاب آشپزی مهاجرت ببینید.

مراحل مهاجرت برای گزارش CSP

به دو روش می‌توان گزارش‌های نقض Content-Security-Policy را پیکربندی کرد:

  • تنها با هدر CSP از طریق دستورالعمل report-uri . این از مرورگر گسترده ای در کروم، فایرفاکس، سافاری و اج پشتیبانی می کند. گزارش‌ها با application/csp-report نوع محتوا ارسال می‌شوند و فرمتی دارند که مختص CSP است. این گزارش ها "گزارش های سطح 2 CSP" نامیده می شوند و به گزارش API متکی نیستند .
  • با گزارش API، از طریق هدر Report-To (میراث) یا Reporting-Endpoints جدیدتر (v1). این فقط در Chrome و Edge پشتیبانی می‌شود. فرمت درخواست‌های گزارش مانند سایر درخواست‌های Reporting API و همان نوع محتوا application/reports+json است.

استفاده از رویکرد اول (فقط report-uri ) دیگر توصیه نمی شود و استفاده از رویکرد دوم مزایای کمی دارد. به طور خاص، به شما امکان می‌دهد از یک راه واحد برای تنظیم گزارش برای همه انواع گزارش و همچنین تنظیم یک نقطه پایانی عمومی استفاده کنید (زیرا همه درخواست‌های گزارش ایجاد شده از طریق Reporting API⏤CSP و موارد دیگر⏤با فرمت یکسان application/reports+json هستند. application/reports+json

با این حال، فقط تعداد کمی از مرورگرها report-to پشتیبانی می کنند . بنابراین توصیه می‌شود report-uri در کنار رویکرد Reporting API ( Report-To یا بهتر، Reporting-Endpoints ) نگه دارید تا گزارش‌های نقض CSP را از چندین مرورگر دریافت کنید. در مرورگری که report-uri و report-to تشخیص می دهد، در صورت وجود report-to report-uri نادیده گرفته می شود. در مرورگری که فقط report-uri می شناسد، فقط report-uri در نظر گرفته می شود.

  1. مرحله 1 (اکنون انجام دهید) : اگر هنوز آن را اضافه نکرده اید، report-to در کنار report-uri اضافه کنید. مرورگرهایی که فقط report-uri (Firefox) پشتیبانی می‌کنند، report-uri استفاده می‌کنند و مرورگرهایی که report-to (Chrome، Edge) نیز پشتیبانی می‌کنند، report-to استفاده می‌کنند. برای مشخص کردن نقاط پایانی نام‌گذاری شده‌ای که در report-to استفاده می‌کنید، از هر دو سرصفحه Report-To و Reporting-Endpoints استفاده کنید. این تضمین می‌کند که گزارش‌هایی را از مشتریان قدیمی‌تر و جدیدتر Chrome و Edge دریافت می‌کنید.

  2. مرحله 3 (زمان شروع): هنگامی که همه یا بیشتر کاربران شما به نصب های بعدی Chrome یا Edge (96 و بالاتر) به روز شدند، Report-To (v0) را حذف کنید و فقط Reporting-Endpoints نگه دارید. report-uri نگه دارید تا همچنان گزارش هایی برای مرورگرهایی که فقط از آن پشتیبانی می کنند دریافت کنید.

نمونه کد این مراحل را در انتقال گزارش CSP ببینید.

مهاجرت: کد نمونه

نمای کلی

اگر از API گزارش‌دهی قدیمی (v0) برای دریافت گزارش‌های نقض برای aa COOP (سرصفحه Cross-Origin-Opener-Policy )، COEP ( Cross-Origin-Embedder-Policy ) یا خط‌مشی سند (سرصفحه Document-Policy ) استفاده می‌کنید. ): با انتقال به Reporting API v1، نیازی به تغییر این سرصفحه های خط مشی ندارید. آنچه شما نیاز دارید این است که از هدر قدیمی Report-To به سربرگ جدید Reporting-Endpoints مهاجرت کنید.

اگر از API قدیمی Reporting (v0) برای دریافت گزارش تخلف برای یک CSP (سربرگ Content-Security-Policy ) استفاده می کنید، ممکن است لازم باشد Content-Security-Policy خود را به عنوان بخشی از انتقال خود به API گزارش جدید تغییر دهید ( v1).

مهاجرت اساسی

کد قدیمی (با v0) 
Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }
کد جدید (کد انتقال با v0 در کنار v1) 
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/default" }] }

اگر از قبل قابلیت گزارش دهی در سایت خود دارید، Report-To فقط به طور موقت نگه دارید (تا زمانی که اکثر کلاینت های Chrome و Edge به روز شوند) تا از دست دادن گزارش ها جلوگیری کنید.

اگر به گزارش خطای شبکه نیاز دارید، Report-To نگه دارید تا زمانی که جایگزینی گزارش خطای شبکه در دسترس قرار گیرد .

کد جدید (فقط با v1) 
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

زمانی که اکثر کلاینت‌های Chrome و Edge به‌روزرسانی شوند و از API v1 پشتیبانی کنند، کد شما در آینده می‌تواند به این شکل باشد.

توجه داشته باشید که با v1، همچنان می‌توانید انواع گزارش‌های خاص را به نقاط پایانی خاص ارسال کنید. اما شما می توانید تنها یک URL در هر نقطه پایانی داشته باشید.

مشاهده تمامی صفحات

کد قدیمی (با v0)، به عنوان مثال با Express 
app.get("/", (request, response) => {
  response.set("Report-To", …)
  response.render(...)
});
app.get("/page1", (request, response) => {
  response.render(...)
});

با v0، می‌توانید نقاط پایانی گزارش را فقط برای برخی از پاسخ‌ها تنظیم کنید. سایر اسناد (صفحات) در آن مبدا به طور خودکار از این نقاط پایانی محیطی استفاده می کنند. در اینجا، نقاط پایانی تنظیم شده برای "/" برای همه پاسخ ها، به عنوان مثال برای page1 استفاده می شود.

کد جدید (با v1)، به عنوان مثال با Express 
// Use a middleware to set the reporting endpoint(s) for *all* requests.
app.use(function(request, response, next) {
  response.set("Reporting-Endpoints", …);
  next();
});

app.get("/", (request, response) => {
  response.render(...)
});

app.get("/page1", (request, response) => {
  response.render(...)
});

با v1، باید سرصفحه Reporting-Endpoints را روی تمام پاسخ هایی که ممکن است گزارش ایجاد کنند، تنظیم کنید.

مهاجرت گزارش CSP

کد قدیمی، فقط با گزارش-uri 
Content-Security-Policy: ...; report-uri https://reports.example/main

استفاده از report-uri دیگر توصیه نمی شود . اگر کد شما مانند بالا است، مهاجرت کنید. نمونه های کد جدید را در زیر ببینید (به رنگ سبز).

کد قدیمی بهتر، با گزارش-uri و دستورالعمل گزارش به با هدر Report-To (v0) 
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Report-To: main-endpoint="https://reports.example/main"

این بهتر است: این کد از report-to استفاده می کند که جایگزین جدیدتر برای report-uri است. همچنان گزارش-uri را برای سازگاری با عقب نگه می دارد. چندین مرورگر report-to پشتیبانی نمی کنند اما از report-uri پشتیبانی می کنند.

با این حال، این می تواند بهتر باشد: این کدها از Reporting API v0 (هدر Report-To ) استفاده می کنند. مهاجرت به نسخه 1: نمونه های "کد جدید" را در زیر ببینید (به رنگ سبز).

کد جدید، با گزارش-uri و دستورالعمل گزارش به با سربرگ Reporting-Endpoints (v1) 
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Reporting-Endpoints: main-endpoint="https://reports.example/main"
Report-To: ...

دستورالعمل report-uri را در کنار report-to دستورالعمل نگه دارید تا زمانی که دستورالعمل report-to در مرورگرها پشتیبانی شود. جدول سازگاری مرورگر را ببینید.

به طور موقت Report-To در کنار Reporting-Endpoints نگه دارید. هنگامی که اکثر بازدیدکنندگان Chrome و Edge شما به بیش از ۹۶ نسخه مرورگر ارتقا یافتند، Report-To را حذف کنید.

در ادامه مطلب

با تشکر فراوان از Ian Clelland، Eiji Kitamura و Milica Mihajlija برای نظرات و پیشنهاداتشان در مورد این مقاله.