التعرّف على حالة الرمز باستخدام ReportingMonitorer API

العثور على واجهات برمجة التطبيقات المتوقّفة نهائيًا في تطبيقاتك العلنية

يُعلمك ReportingObserver عندما يستخدم موقعك الإلكتروني واجهة برمجة تطبيقات متوقّفة نهائيًا أو يواجه تدخلًا من المتصفّح. تم طرح الوظائف الأساسية في Chrome 69. وبدءًا من الإصدار 84 من Chrome، يمكن استخدامها في مهام Chrome.

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

observer.observe();

استخدِم دالة "الرجوع" لإرسال التقارير إلى الخلفية أو مقدّم خدمة إحصاءات بهدف التحليل.

ما هو الغرض من ذلك؟ وحتى ظهور واجهة برمجة التطبيقات هذه، كانت التحذيرات بشأن الإيقاف النهائي للميزات والتدخلات متاحة فقط في "أدوات مطوّري البرامج" كرسائل في وحدة التحكّم. لا يتم بدء التدخلات، على وجه الخصوص، إلا بسبب قيود مختلفة في العالم الواقعي، مثل شروط الجهاز والشبكة. وبالتالي، قد لا تظهر لك هذه الرسائل أبدًا عند تطوير/اختبار موقع إلكتروني على الجهاز. ReportingObserver يقدّم حلًا لهذه المشكلة. عندما يواجه المستخدمون مشاكل محتملة في الإصدار العلني، يمكن إرسال إشعارات إلى مطوّري الويب بشأنها.

الخلفية

لقد كتبت منذ فترة مشاركة مدوّنة (مراقبة تطبيق الويب الخاص بك) لأنّ عدد واجهات برمجة التطبيقات (APIs) المتاحة لمراقبة "العناصر" التي تحدث في تطبيق الويب رائع، على سبيل المثال، هناك واجهات برمجة تطبيقات يمكنها مراقبة معلومات حول DOM: ResizeObserver، IntersectionObserver، MutationObserver. PerformanceObserver تُسجِّل قياسات الأداء. وتتيح لنا أيضًا طرق مثل window.onerror و window.onunhandledrejection إعلامنا عند حدوث خطأ.

ومع ذلك، هناك أنواع أخرى من التحذيرات لا ترصدها واجهات برمجة التطبيقات الحالية. عندما يستخدم موقعك الإلكتروني واجهة برمجة تطبيقات متوقّفة نهائيًا أو يواجه تدخلًا من المتصفّح، تكون "أدوات المطوّر" هي أول من يُعلمك بهما:

تحذيرات "وحدة تحكّم أدوات مطوّري البرامج في Chrome" بشأن الإيقاف النهائي للميزات والتدخلات
التحذيرات التي يبدأها المتصفّح في "وحدة تحكّم أدوات مطوّري البرامج"

قد يعتقد المرء بشكل طبيعي أنّ window.onerror يسجّل هذه التحذيرات. لا، لا يفعل ذلك. ويعود السبب في ذلك إلى أنّ window.onerror لا يتم تشغيله للإنذارات التي يتم إنشاؤها مباشرةً من قِبل وكيل المستخدم نفسه. يتم تنشيطه بسبب أخطاء وقت التشغيل (استثناءات JavaScript وأخطاء البنية) الناتجة عن تنفيذ الرمز البرمجي.

يحلّ 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();

تلقّي إشعارات عند إزالة واجهات برمجة التطبيقات

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 واجهة برمجة التطبيقات الفعلية لرصد جميع أنواع المشاكل في JavaScript. تخيل واجهة برمجة تطبيقات واحدة لرصد كل الصعوبات التي تواجهها في تطبيقك:

مراجع إضافية:

الصورة الرئيسية من تأليف Sieuwert Otterloo على Unsplash.