logoNext.js العربية
التوثيقالمدونةالتعلم
مقدمة/أدلة إرشادية/التحليلات

كيفية إضافة التحليلات إلى تطبيق Next.js الخاص بك

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

أدوات العميل

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

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

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

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

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

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.

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

مقاييس الويب الأساسية (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
      }
      // ...
    }
  })
}

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

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

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.

أدلة إرشادية

تعلم كيفية تنفيذ أنماط واجهة المستخدم الشائعة وحالات الاستخدام باستخدام Next.js

المصادقة

تعلم كيفية تنفيذ المصادقة في تطبيق Next.js الخاص بك.