useReportWebVitals

يتيح لك خطاف useReportWebVitals الإبلاغ عن مؤشرات ويب الأساسية (Core Web Vitals)، ويمكن استخدامه بالاشتراك مع خدمة التحليلات الخاصة بك.

يتم استدعاء الوظائف الجديدة الممررة إلى useReportWebVitals مع المقاييس المتاحة حتى تلك اللحظة. لمنع الإبلاغ عن بيانات مكررة، تأكد من أن مرجع دالة رد الاتصال لا يتغير (كما هو موضح في أمثلة الكود أدناه).

pages/_app.js

import { useReportWebVitals } from 'next/web-vitals'

const logWebVitals = (metric) => {
  console.log(metric)
}

function MyApp({ Component, pageProps }) {
  useReportWebVitals(logWebVitals)

  return <Component {...pageProps} />
}

يتكون كائن metric الممرر كوسيطة للخطاف من عدد من الخصائص:

id: معرف فريد للمقياس في سياق تحميل الصفحة الحالي
name: اسم مقياس الأداء. القيم المحتملة تشمل أسماء مقاييس مؤشرات ويب الأساسية (TTFB, FCP, LCP, FID, CLS) المحددة لتطبيق ويب.
delta: الفرق بين القيمة الحالية والقيمة السابقة للمقياس. القيمة عادةً ما تكون بالمللي ثانية وتمثل التغيير في قيمة المقياس بمرور الوقت.
entries: مصفوفة من إدخالات الأداء (Performance Entries) المرتبطة بالمقياس. توفر هذه الإدخالات معلومات مفصلة حول أحداث الأداء المتعلقة بالمقياس.
navigationType: يشير إلى نوع التنقل (type of navigation) الذي أطلق جمع المقياس. القيم المحتملة تشمل "navigate", "reload", "back_forward", و "prerender".
rating: تقييم نوعي لقيمة المقياس، يوفر تقييمًا للأداء. القيم المحتملة هي "good", "needs-improvement", و "poor". يتم تحديد التقييم عادةً بمقارنة قيمة المقياس مع عتبات محددة مسبقًا تشير إلى أداء مقبول أو دون المستوى الأمثل.
value: القيمة الفعلية أو مدة إدخال الأداء، عادةً بالمللي ثانية. توفر القيمة مقياسًا كميًا لجانب الأداء الذي يتم تتبعه بواسطة المقياس. يعتمد مصدر القيمة على المقياس المحدد الذي يتم قياسه ويمكن أن يأتي من واجهات Performance API المختلفة.

مؤشرات ويب الأساسية (Web Vitals)

مؤشرات ويب الأساسية (Web Vitals) هي مجموعة من المقاييس المفيدة التي تهدف إلى التقاط تجربة المستخدم لصفحة ويب. تتضمن مؤشرات الويب الأساسية التالية:

يمكنك التعامل مع جميع نتائج هذه المقاييس باستخدام خاصية name.

pages/_app.js

import { useReportWebVitals } from 'next/web-vitals'

const handleWebVitals = (metric) => {
  switch (metric.name) {
    case 'FCP': {
      // التعامل مع نتائج FCP
    }
    case 'LCP': {
      // التعامل مع نتائج LCP
    }
    // ...
  }
}

function MyApp({ Component, pageProps }) {
  useReportWebVitals(handleWebVitals)

  return <Component {...pageProps} />
}

مقاييس مخصصة

بالإضافة إلى المقاييس الأساسية المذكورة أعلاه، هناك بعض المقاييس المخصصة الإضافية التي تقيس الوقت الذي تستغرقه الصفحة للترطيب (hydration) والرسم:

Next.js-hydration: طول الوقت الذي تستغرقه الصفحة لبدء وإنهاء الترطيب (بالملي ثانية)
Next.js-route-change-to-render: طول الوقت الذي تستغرقه الصفحة لبدء الرسم بعد تغيير المسار (بالملي ثانية)
Next.js-render: طول الوقت الذي تستغرقه الصفحة لإنهاء الرسم بعد تغيير المسار (بالملي ثانية)

يمكنك التعامل مع جميع نتائج هذه المقاييس بشكل منفصل:

pages/_app.js

import { useReportWebVitals } from 'next/web-vitals'

function handleCustomMetrics(metrics) {
  switch (metric.name) {
    case 'Next.js-hydration':
      // التعامل مع نتائج الترطيب
      break
    case 'Next.js-route-change-to-render':
      // التعامل مع نتائج تغيير المسار إلى الرسم
      break
    case 'Next.js-render':
      // التعامل مع نتائج الرسم
      break
    default:
      break
  }
}

function MyApp({ Component, pageProps }) {
  useReportWebVitals(handleCustomMetrics)

  return <Component {...pageProps} />
}

تعمل هذه المقاييس في جميع المتصفحات التي تدعم واجهة برمجة تطبيقات توقيت المستخدم (User Timing API).

إرسال النتائج إلى أنظمة خارجية

يمكنك إرسال النتائج إلى أي نقطة نهاية لقياس وتتبع أداء المستخدم الحقيقي على موقعك. على سبيل المثال:

function postWebVitals(metrics) {
  const body = JSON.stringify(metric)
  const url = 'https://example.com/analytics'

  // استخدم `navigator.sendBeacon()` إذا كان متاحًا، مع التراجع إلى `fetch()`.
  if (navigator.sendBeacon) {
    navigator.sendBeacon(url, body)
  } else {
    fetch(url, { body, method: 'POST', keepalive: true })
  }
}

useReportWebVitals(postWebVitals)

من الجيد معرفة: إذا كنت تستخدم Google Analytics، فإن استخدام قيمة id يمكن أن يسمح لك ببناء توزيعات المقاييس يدويًا (لحساب النسب المئوية، إلخ.)

useReportWebVitals(metric => {
  // استخدم `window.gtag` إذا قمت بتهيئة Google Analytics كما في هذا المثال:
  // https://github.com/vercel/next.js/blob/canary/examples/with-google-analytics
  window.gtag('event', metric.name, {
    value: Math.round(metric.name === 'CLS' ? metric.value * 1000 : metric.value), // يجب أن تكون القيم أعدادًا صحيحة
    event_label: metric.id, // معرف فريد لتحميل الصفحة الحالي
    non_interaction: true, // يتجنب التأثير على معدل الارتداد.
  });
}

اقرأ المزيد حول إرسال النتائج إلى Google Analytics.

useReportWebVitals