كيفية إعداد التحليلات

يحتوي Next.js على دعم مدمج لقياس وإعداد تقارير لمقاييس الأداء. يمكنك إما استخدام خطاف useReportWebVitals لإدارة التقارير بنفسك، أو بدلاً من ذلك، توفر Vercel خدمة مُدارة لجمع وعرض المقاييس تلقائيًا لك.

أدوات العميل

للاحتياجات الأكثر تقدمًا في التحليلات والمراقبة، يوفر Next.js ملف instrumentation-client.js|ts الذي يعمل قبل بدء تنفيذ كود واجهة التطبيق. هذا مثالي لإعداد أدوات التحليلات العالمية، تتبع الأخطاء، أو مراقبة الأداء.

لاستخدامه، قم بإنشاء ملف instrumentation-client.js أو instrumentation-client.ts في الدليل الجذر لتطبيقك:

// تهيئة التحليلات قبل بدء التطبيق
console.log('تم تهيئة التحليلات')

// إعداد تتبع الأخطاء العالمي
window.addEventListener('error', (event) => {
  // إرسال إلى خدمة تتبع الأخطاء الخاصة بك
  reportError(event.error)
})

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

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

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

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

عرض مرجع API لمزيد من المعلومات.

مقاييس الويب الأساسية (Web Vitals)

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

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

يمكنك التعامل مع جميع نتائج هذه المقاييس باستخدام خاصية name.

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: المدة التي تستغرقها الصفحة لإنهاء العرض بعد تغيير المسار (بالميلي ثانية)

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

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).

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

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

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