مكتبات الطرف الثالث

@next/third-parties هي مكتبة توفر مجموعة من المكونات والأدوات التي تحسن الأداء وتجربة المطور لتحميل مكتبات الطرف الثالث الشهيرة في تطبيق Next.js الخاص بك.

جميع تكاملات الطرف الثالث المقدمة من @next/third-parties تم تحسينها للأداء وسهولة الاستخدام.

البدء

للبدء، قم بتثبيت مكتبة @next/third-parties:

Terminal

npm install @next/third-parties@latest next@latest

@next/third-parties حاليًا مكتبة تجريبية قيد التطوير النشط. نوصي بتثبيتها باستخدام علامات latest أو canary بينما نعمل على إضافة المزيد من تكاملات الطرف الثالث.

مكتبات جوجل للطرف الثالث

جميع مكتبات الطرف الثالث المدعومة من جوجل يمكن استيرادها من @next/third-parties/google.

مدير علامات جوجل (Google Tag Manager)

يمكن استخدام مكون GoogleTagManager لإنشاء حاوية مدير علامات جوجل في صفحتك. افتراضيًا، يقوم بجلب النص البرمجي المضمن الأصلي بعد حدوث التمهيد (hydration) في الصفحة.

لتحميل مدير علامات جوجل لجميع المسارات، قم بتضمين المكون مباشرة في تخطيط الجذر الخاص بك ومرر معرف حاوية GTM:

import { GoogleTagManager } from '@next/third-parties/google'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <GoogleTagManager gtmId="GTM-XYZ" />
      <body>{children}</body>
    </html>
  )
}

import { GoogleTagManager } from '@next/third-parties/google'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <GoogleTagManager gtmId="GTM-XYZ" />
      <body>{children}</body>
    </html>
  )
}

لتحميل مدير علامات جوجل لمسار واحد، قم بتضمين المكون في ملف الصفحة الخاص بك:

app/page.js

import { GoogleTagManager } from '@next/third-parties/google'

export default function Page() {
  return <GoogleTagManager gtmId="GTM-XYZ" />
}

يمكن استخدام دالة sendGTMEvent لتتبع تفاعلات المستخدم في صفحتك عن طريق إرسال أحداث باستخدام كائن dataLayer. لكي تعمل هذه الدالة، يجب تضمين مكون <GoogleTagManager /> إما في تخطيط أصل، أو صفحة، أو مكون، أو مباشرة في نفس الملف.

app/page.js

'use client'

import { sendGTMEvent } from '@next/third-parties/google'

export function EventButton() {
  return (
    <div>
      <button
        onClick={() => sendGTMEvent({ event: 'buttonClicked', value: 'xyz' })}
      >
        إرسال حدث
      </button>
    </div>
  )
}

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

الخيارات

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

الاسم	النوع	الوصف
`gtmId`	مطلوب	معرف حاوية GTM الخاص بك. عادةً ما يبدأ بـ `GTM-`.
`dataLayer`	اختياري	مصفوفة طبقة البيانات لإنشاء الحاوية بها. الافتراضي هو مصفوفة فارغة.
`dataLayerName`	اختياري	اسم طبقة البيانات. الافتراضي هو `dataLayer`.
`auth`	اختياري	قيمة معلمة المصادقة (`gtm_auth`) لمقتطفات البيئة.
`preview`	اختياري	قيمة معلمة المعاينة (`gtm_preview`) لمقتطفات البيئة.

تحليلات جوجل (Google Analytics)

يمكن استخدام مكون GoogleAnalytics لتضمين تحليلات جوجل 4 في صفحتك عبر علامة جوجل (gtag.js). افتراضيًا، يقوم بجلب النصوص البرمجية الأصلية بعد حدوث التمهيد (hydration) في الصفحة.

توصية: إذا كان مدير علامات جوجل مضمنًا بالفعل في تطبيقك، يمكنك تكوين تحليلات جوجل مباشرة باستخدامه، بدلاً من تضمين تحليلات جوجل كمكون منفصل. راجع الوثائق لمعرفة المزيد عن الاختلافات بين مدير العلامات وgtag.js.

لتحميل تحليلات جوجل لجميع المسارات، قم بتضمين المكون مباشرة في تخطيط الجذر الخاص بك ومرر معرف القياس الخاص بك:

import { GoogleAnalytics } from '@next/third-parties/google'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
      <GoogleAnalytics gaId="G-XYZ" />
    </html>
  )
}

import { GoogleAnalytics } from '@next/third-parties/google'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
      <GoogleAnalytics gaId="G-XYZ" />
    </html>
  )
}

لتحميل تحليلات جوجل لمسار واحد، قم بتضمين المكون في ملف الصفحة الخاص بك:

app/page.js

import { GoogleAnalytics } from '@next/third-parties/google'

export default function Page() {
  return <GoogleAnalytics gaId="G-XYZ" />
}

إرسال الأحداث

يمكن استخدام دالة sendGAEvent لقياس تفاعلات المستخدم في صفحتك عن طريق إرسال أحداث باستخدام كائن dataLayer. لكي تعمل هذه الدالة، يجب تضمين مكون <GoogleAnalytics /> إما في تخطيط أصل، أو صفحة، أو مكون، أو مباشرة في نفس الملف.

app/page.js

'use client'

import { sendGAEvent } from '@next/third-parties/google'

export function EventButton() {
  return (
    <div>
      <button
        onClick={() => sendGAEvent({ event: 'buttonClicked', value: 'xyz' })}
      >
        إرسال حدث
      </button>
    </div>
  )
}

راجع وثائق المطور لتحليلات جوجل لمعرفة المزيد عن معلمات الأحداث.

تتبع مشاهدات الصفحات

تقوم تحليلات جوجل تلقائيًا بتتبع مشاهدات الصفحات عند تغيير حالة سجل المتصفح. هذا يعني أن التنقلات بين مسارات Next.js من جانب العميل سترسل بيانات مشاهدات الصفحات دون أي تكوين.

للتأكد من قياس التنقلات من جانب العميل بشكل صحيح، تحقق من تمكين خاصية "القياس المعزز" في لوحة التحكم الخاصة بك وتحديد خانة الاختيار "تغييرات الصفحة بناءً على أحداث سجل المتصفح".

ملاحظة: إذا قررت إرسال أحداث مشاهدات الصفحات يدويًا، تأكد من تعطيل قياس مشاهدات الصفحات الافتراضي لتجنب وجود بيانات مكررة. راجع وثائق المطور لتحليلات جوجل لمعرفة المزيد.

الخيارات

خيارات لتمريرها إلى مكون <GoogleAnalytics>.

الاسم	النوع	الوصف
`gaId`	مطلوب	معرف القياس الخاص بك. عادةً ما يبدأ بـ `G-`.
`dataLayerName`	اختياري	اسم طبقة البيانات. الافتراضي هو `dataLayer`.

تضمين خرائط جوجل (Google Maps Embed)

يمكن استخدام مكون GoogleMapsEmbed لإضافة تضمين خرائط جوجل إلى صفحتك. افتراضيًا، يستخدم سمة loading للتحميل البطيء (lazy-load) للتضمين أسفل الطية (below the fold).

app/page.js

import { GoogleMapsEmbed } from '@next/third-parties/google'

export default function Page() {
  return (
    <GoogleMapsEmbed
      apiKey="XYZ"
      height={200}
      width="100%"
      mode="place"
      q="Brooklyn+Bridge,New+York,NY"
    />
  )
}

الخيارات

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

الاسم	النوع	الوصف
`apiKey`	مطلوب	مفتاح API الخاص بك.
`mode`	مطلوب	وضع الخريطة
`height`	اختياري	ارتفاع التضمين. الافتراضي هو `auto`.
`width`	اختياري	عرض التضمين. الافتراضي هو `auto`.
`style`	اختياري	تطبيق أنماط على iframe.
`allowfullscreen`	اختياري	خاصية للسماح لأجزاء معينة من الخريطة بالذهاب إلى وضع ملء الشاشة.
`loading`	اختياري	الافتراضي هو lazy. فكر في تغييره إذا كنت تعلم أن التضمين الخاص بك سيكون فوق الطية.
`q`	اختياري	يحدد موقع علامة الخريطة. قد يكون هذا مطلوبًا اعتمادًا على وضع الخريطة.
`center`	اختياري	يحدد مركز عرض الخريطة.
`zoom`	اختياري	يحدد مستوى التكبير الأولي للخريطة.
`maptype`	اختياري	يحدد نوع بلاط الخريطة للتحميل.
`language`	اختياري	يحدد اللغة المستخدمة لعناصر واجهة المستخدم وعرض التسميات على بلاط الخريطة.
`region`	اختياري	يحدد الحدود والتسميات المناسبة للعرض، بناءً على الحساسيات الجيوسياسية.

تضمين يوتيوب (YouTube Embed)

يمكن استخدام مكون YouTubeEmbed لتحميل وعرض تضمين يوتيوب. يقوم هذا المكون بالتحميل بشكل أسرع باستخدام lite-youtube-embed في الخلفية.

app/page.js

import { YouTubeEmbed } from '@next/third-parties/google'

export default function Page() {
  return <YouTubeEmbed videoid="ogfYd705cRs" height={400} params="controls=0" />
}

الخيارات

الاسم	النوع	الوصف
`videoid`	مطلوب	معرف فيديو يوتيوب.
`width`	اختياري	عرض حاوية الفيديو. الافتراضي هو `auto`
`height`	اختياري	ارتفاع حاوية الفيديو. الافتراضي هو `auto`
`playlabel`	اختياري	تسمية مخفية بصريًا لزر التشغيل لإمكانية الوصول.
`params`	اختياري	معلمات مشغل الفيديو المحددة هنا. يتم تمرير المعلمات كسلسلة استعلام. مثال: `params="controls=0&start=10&end=30"`
`style`	اختياري	يستخدم لتطبيق الأنماط على حاوية الفيديو.

On this page