التحليلات

يتيح لك Next.js Speed Insights تحليل وقياس أداء الصفحات باستخدام مقاييس مختلفة.

يمكنك البدء في جمع درجة التجربة الحقيقية بدون أي تكوين مسبق على نشرات Vercel.

يصف باقي هذا التوثيق جهاز إعادة التوجيه المدمج الذي يستخدمه Next.js Speed Insights.

بناء نظامك الخاص

أولاً، ستحتاج إلى إنشاء مكون تطبيق مخصص وتحديد دالة reportWebVitals:

export function reportWebVitals(metric) {
  console.log(metric)
}

function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />
}

export default MyApp

يتم تنشيط هذه الدالة عند اكتمال حساب القيم النهائية لأي من المقاييس على الصفحة. يمكنك استخدامها لتسجيل أي من النتائج في وحدة التحكم أو إرسالها إلى نقطة نهاية معينة.

يتكون كائن metric الذي يتم إرجاعه إلى الدالة من عدد من الخصائص:

• id: معرف فريد للمقياس في سياق تحميل الصفحة الحالي
• name: اسم المقياس
• startTime: الطابع الزمني الأول المسجل لإدخال الأداء بوحدة الميللي ثانية (إذا كان مطبقًا)
• value: القيمة، أو المدة بوحدة الميللي ثانية، لإدخال الأداء
• label: نوع المقياس (web-vital أو custom)

هناك نوعان من المقاييس التي يتم تتبعها:

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

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

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

• الوقت حتى أول بايت (TTFB)
• أول رسم للمحتوى (FCP)
• أكبر رسم للمحتوى (LCP)
• تأخر أول إدخال (FID)
• تراكم تحول التخطيط (CLS)
• التفاعل حتى الرسم التالي (INP) (تجريبي)

يمكنك معالجة جميع نتائج هذه المقاييس باستخدام التسمية web-vital:

export function reportWebVitals(metric) {
  if (metric.label === 'web-vital') {
    console.log(metric) // يتم تسجيل كائن المقياس ({ id, name, startTime, value, label }) في وحدة التحكم
  }
}

هناك أيضًا خيار معالجة كل مقياس على حدة:

export function reportWebVitals(metric) {
  switch (metric.name) {
    case 'FCP':
      // معالجة نتائج FCP
      break
    case 'LCP':
      // معالجة نتائج LCP
      break
    case 'CLS':
      // معالجة نتائج CLS
      break
    case 'FID':
      // معالجة نتائج FID
      break
    case 'TTFB':
      // معالجة نتائج TTFB
      break
    case 'INP':
      // معالجة نتائج INP (ملاحظة: INP لا يزال مقياسًا تجريبيًا)
      break
    default:
      break
  }
}

يتم استخدام مكتبة طرف ثالث، web-vitals، لقياس هذه المقاييس. يعتمد توافق المتصفح على المقياس المحدد، لذا راجع قسم دعم المتصفحات لمعرفة المتصفحات المدعومة.

المقاييس المخصصة

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

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

يمكنك معالجة جميع نتائج هذه المقاييس باستخدام التسمية custom:

export function reportWebVitals(metric) {
  if (metric.label === 'custom') {
    console.log(metric) // يتم تسجيل كائن المقياس ({ id, name, startTime, value, label }) في وحدة التحكم
  }
}

هناك أيضًا خيار معالجة كل مقياس على حدة:

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
  }
}

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

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

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

export function reportWebVitals(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 يمكن أن يسمح لك ببناء توزيعات المقاييس يدويًا (لحساب النسب المئوية، إلخ.)

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

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

TypeScript

إذا كنت تستخدم TypeScript، يمكنك استخدام النوع المدمج NextWebVitalsMetric:

import type { AppProps, NextWebVitalsMetric } from 'next/app'

function MyApp({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />
}

export function reportWebVitals(metric: NextWebVitalsMetric) {
  console.log(metric)
}

export default MyApp

function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />
}

export function reportWebVitals(metric) {
  console.log(metric)
}

export default MyApp