useReportWebVitals

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

pages/_app.js

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

function MyApp({ Component, pageProps }) {
  useReportWebVitals((metric) => {
    console.log(metric)
  })

  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'

function MyApp({ Component, pageProps }) {
  useReportWebVitals((metric) => {
    switch (metric.name) {
      case 'FCP': {
        // التعامل مع نتائج FCP
      }
      case 'LCP': {
        // التعامل مع نتائج LCP
      }
      // ...
    }
  })

  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 MyApp({ Component, pageProps }) {
  useReportWebVitals((metric) => {
    switch (metric.name) {
      case 'Next.js-hydration':
        // التعامل مع نتائج الترطيب
        break
      case 'Next.js-route-change-to-render':
        // التعامل مع نتائج تغيير المسار إلى الرسم
        break
      case 'Next.js-render':
        // التعامل مع نتائج الرسم
        break
      default:
        break
    }
  })

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

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

الاستخدام على Vercel

إحصاءات سرعة Vercel (Vercel Speed Insights) يتم تكوينها تلقائيًا على نشرات Vercel، ولا تتطلب استخدام useReportWebVitals. هذا الخطاف مفيد في التطوير المحلي، أو إذا كنت تستخدم خدمة تحليلات مختلفة.

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

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

useReportWebVitals((metric) => {
  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 })
  }
})

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

useReportWebVitals(metric => {
  // استخدم `window.gtag` إذا قمت بتهيئة Google Analytics كما في هذا المثال:
  // https://github.com/vercel/next.js/blob/canary/examples/with-google-analytics/pages/_app.js
  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