با ReportingObserver API از سلامت کدتان مطلع شوید

میاناهای برنامه‌سازی کاربردی منسوخ‌شده را در برنامه‌های تولیدی‌تان پیدا کنید.

ReportingObserver به شما اطلاع می‌دهد که سایتتان چه زمانی از میانای برنامه‌سازی کاربردی منسوخ‌شده استفاده می‌کند یا با مداخله مرورگر مواجه می‌شود. عملکرد اصلی در ابتدا در Chrome 69 ارائه شد. از Chrome 84، می‌توان از آن در worker استفاده کرد.

const observer = new ReportingObserver((reports, observer) => {
  for (const report of reports) {
    console.log(report.type, report.url, report.body);
  }
}, {buffered: true});

observer.observe();

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

چرا این مفید است؟ تا پیش‌از این میانای برنامه‌سازی کاربردی، هشدارهای مداخله و منسوخ شدن فقط در DevTools به‌عنوان پیام‌های «کنسول» دردسترس بودند. به‌ویژه، مداخلات فقط با محدودیت‌های مختلف دنیای واقعی مانند شرایط دستگاه و شبکه راه‌اندازی می‌شوند. بنابراین، ممکن است حتی هنگام توسعه/آزمایش کردن سایت به‌صورت محلی، این پیام‌ها را نبینید. ReportingObserver راه حلی برای این مشکل ارائه می‌دهد. وقتی کاربران در محیط واقعی با مشکلات احتمالی مواجه می‌شوند، توسعه‌دهندگان وب می‌توانند از آن‌ها مطلع شوند.

پس‌زمینه

چندی پیش، یک پست وبلاگ (مشاهده برنامه وب شما) نوشتم زیرا برایم جالب بود که چقدر API برای نظارت بر «چیزهایی» که در یک برنامه وب اتفاق می‌افتد وجود دارد. برای مثال، APIهایی وجود دارند که می‌توانند اطلاعات مربوط به DOM را مشاهده کنند: ResizeObserver، IntersectionObserver، MutationObserver. PerformanceObserver اندازه‌گیری‌های عملکرد را ضبط می‌کند. و روش‌هایی مثل window.onerror و window.onunhandledrejection حتی وقتی مشکلی پیش می‌آید به ما اطلاع می‌دهند.

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

هشدارهای «کنسول DevTools» برای منسوخ شدن و مداخله.
هشدارهای آغازشده توسط مرورگر در «کنسول DevTools».

طبیعتاً فکر می‌کنید window.onerror این هشدارها را ثبت می‌کند. این‌طور نیست. دلیلش این است که window.onerror برای هشدارهایی که مستقیماً توسط خود نماینده کاربر تولید می‌شود، فعال نمی‌شود. این رویداد برای خطاهای زمان اجرا (استثناهای جاوا اسکریپت و خطاهای نحوی) ناشی از اجرای کد فعال می‌شود.

‫ReportingObserver کار را ادامه می‌دهد. این میانا روشی برنامه‌نویسی‌شده برای مطلع شدن از هشدارهای صادرشده ازسوی مرورگر، مانند منسوخ‌سازی‌ها و مداخلات، ارائه می‌دهد. می‌توانید از آن به‌عنوان ابزار گزارش‌دهی استفاده کنید و کمتر نگران این باشید که آیا کاربران در سایت زنده شما با مشکلات غیرمنتظره‌ای مواجه می‌شوند یا نه.

میانای برنامه‌سازی کاربردی

ReportingObserver با دیگر میاناهای برنامه‌سازی کاربردی Observer مثل IntersectionObserver و ResizeObserver تفاوتی ندارد. شما به آن تماس برگشتی می‌دهید؛ آن به شما اطلاعات می‌دهد. اطلاعاتی که فراخوانی برگشتی دریافت می‌کند فهرستی از مشکلات است که صفحه باعث آن شده است:

const observer = new ReportingObserver((reports, observer) => {
  for (const report of reports) {
    // → report.type === 'deprecation'
    // → report.url === 'https://reporting-observer-api-demo.glitch.me'
    // → report.body.id === 'XMLHttpRequestSynchronousInNonWorkerOutsideBeforeUnload'
    // → report.body.message === 'Synchronous XMLHttpRequest is deprecated...'
    // → report.body.lineNumber === 11
    // → report.body.columnNumber === 22
    // → report.body.sourceFile === 'https://reporting-observer-api-demo.glitch.me'
    // → report.body.anticipatedRemoval === <JS_DATE_STR> or null
  }
});

observer.observe();

گزارش‌های فیلترشده

گزارش‌ها را می‌توان ازقبل فیلتر کرد تا فقط انواع خاصی از گزارش‌ها مشاهده شود. درحال‌حاضر، دو نوع گزارش وجود دارد: 'deprecation' و 'intervention'.

const observer = new ReportingObserver((reports, observer) => {
  …
}, {types: ['deprecation']});

گزارش‌های میان‌گیری‌شده

وقتی می‌خواهید گزارش‌هایی را که قبل‌از ایجاد نمونه ناظر تولید شده‌اند ببینید، از گزینه buffered: true استفاده کنید:

const observer = new ReportingObserver((reports, observer) => {
  …
}, {types: ['intervention'], buffered: true});

این گزینه برای موقعیت‌هایی مثل بار کردن کُند کتابخانه‌ای که از ReportingObserver استفاده می‌کند عالی است. ناظر دیر اضافه می‌شود، اما هیچ‌چیز را که قبلاً در بار کردن صفحه اتفاق افتاده است ازدست نمی‌دهید.

توقف مشاهده

بااستفاده از روش disconnect()، مشاهده را متوقف کنید:

observer.disconnect();

مثال‌ها

گزارش کردن مداخله‌های مرورگر به ارائه‌دهنده تجزیه‌وتحلیل

const observer = new ReportingObserver((reports, observer) => {
  for (const report of reports) {
    sendReportToAnalytics(JSON.stringify(report.body));
  }
}, {types: ['intervention'], buffered: true});

observer.observe();

وقتی APIها قرار است برداشته شوند، مطلع شوید

const observer = new ReportingObserver((reports, observer) => {
  for (const report of reports) {
    if (report.type === 'deprecation') {
      sendToBackend(`Using a deprecated API in ${report.body.sourceFile} which will be
                     removed on ${report.body.anticipatedRemoval}. Info: ${report.body.message}`);
    }
  }
});

observer.observe();

نتیجه‌گیری

ReportingObserver روش دیگری برای کشف و پایش مشکلات احتمالی در برنامه وب به شما ارائه می‌دهد. حتی ابزار مفیدی برای درک سلامت پایگاه کد شما (یا عدم وجود آن) است. گزارش‌ها را به باطن ارسال کنید، از مشکلات دنیای واقعی مطلع شوید، کد را به‌روز کنید، و سود ببرید!

کار آینده

امیدوارم در آینده ReportingObserver به API واقعی برای گرفتن انواع مشکلات در جاوا اسکریپت تبدیل شود. یک میانای برنامه‌سازی کاربردی را تصور کنید که همه مشکلات برنامه‌تان را شناسایی می‌کند:

منابع تکمیلی:

نگاره اصلی از Sieuwert Otterloo در Unsplash.