useReportWebVitals

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

app/_components/web-vitals.js

'use client'

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

export function WebVitals() {
  useReportWebVitals((metric) => {
    console.log(metric)
  })
}

app/layout.js

import { WebVitals } from './_components/web-vitals'

export default function Layout({ children }) {
  return (
    <html>
      <body>
        <WebVitals />
        {children}
      </body>
    </html>
  )
}

نظرًا لأن خطاف useReportWebVitals يتطلب توجيه "use client"، فإن النهج الأكثر كفاءة هو إنشاء مكون منفصل يستورده التخطيط الجذري. هذا يحصر حدود العميل حصريًا في مكون WebVitals.

كائن 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.

'use client'

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

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

'use client'

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

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

الاستخدام على 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