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: القيمة الفعلية أو مدة إدخال الأداء، عادةً بالميلي ثانية. توفر القيمة مقياسًا كميًا لجانب الأداء الذي يتم تتبعه بواسطة المقياس. يعتمد مصدر القيمة على المقياس المحدد الذي يتم قياسه ويمكن أن يأتي من واجهات أداء API (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} />
}

مقاييس مخصصة

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

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

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

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

تعمل هذه المقاييس في جميع المتصفحات التي تدعم واجهة مستخدم التوقيت (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