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

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

Eric Bidelman

تتيح لك أداة ReportingObserver معرفة ما إذا كان موقعك الإلكتروني يستخدم واجهة برمجة تطبيقات متوقفة نهائيًا أو يواجه تدخلاً من المتصفّح. تم طرح الوظائف الأساسية في الأصل في الإصدار 69 من Chrome. اعتبارًا من الإصدار 84 من 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 حلاً لهذه المشكلة. عندما يواجه المستخدمون مشاكل محتملة في بيئة حقيقية، يمكن إبلاغ مطوِّري تطبيقات الويب بها.

خلفية

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

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

التحذيرات التي يطلقها المتصفّح في "وحدة تحكّم أدوات مطوّري البرامج"

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

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

مصطلح أساسي: ReportingObserver هو جزء من مواصفات أكبر، وهي Reporting API، التي توفّر طريقة شائعة لإرسال هذه التقارير المختلفة إلى الخلفية. ‫Reporting API هي إطار عمل عام لتحديد مجموعة من نقاط نهاية الخادم التي يتم الإبلاغ عن المشاكل إليها.

واجهة برمجة التطبيقات

لا تختلف واجهة برمجة التطبيقات 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. تخيَّل واجهة برمجة تطبيقات واحدة ترصد كل الأخطاء التي تحدث في تطبيقك:

• تدخّلات المتصفّح
• الميزات التي سيتم إيقافها نهائيًا
• انتهاكات سياسة الميزات يُرجى الاطّلاع على مشكلة Chromium رقم 867471.
• استثناءات وأخطاء JS (تتم معالجتها حاليًا من خلال window.onerror)
• عمليات رفض وعود JS غير المعالَجة (تتم معالجتها حاليًا من خلال window.onunhandledrejection)

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

• مواصفات W3c
• إدخال chromestatus.com

الصورة الرئيسية من قِبل Sieuwert Otterloo على Unsplash.