استخدام useReportWebVitals

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

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

app/_components/web-vitals.js

'use client'

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

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

export function WebVitals() {
  useReportWebVitals(logWebVitals)

  return null
}

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.

useReportWebVitals

يتكون كائن 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'

type ReportWebVitalsCallback = Parameters<typeof useReportWebVitals>[0]

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

export function WebVitals() {
  useReportWebVitals(handleWebVitals)
}

'use client'

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

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

export function WebVitals() {
  useReportWebVitals(handleWebVitals)
}

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

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

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

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

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

On this page