کتابخانه های شخص ثالث

@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 می‌توان برای ایجاد یک کانتینر Google Tag Manager (opens in a new tab) در صفحه‌ی شما استفاده کرد. به طور پیش فرض، این اسکریپت درون خطی اصلی را پس از هیدراتاسیون hydration صفحه فراخوانی می‌کند.

برای بارگیری Google Tag Manager برای همه مسیرها، کامپوننت را مستقیماً در طرح بندی ریشه خود قرار دهید و ID کانتینر GTM خود را وارد کنید:

app/layout.tsx

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

برای بارگیری Google Tag Manager برای یک مسیر خاص، کامپوننت را در فایل صفحه‌ی خود قرار دهید:

app/page.js

import { GoogleTagManager } from '@next/third-parties/google'
 
export default function Page() {
	return <GoogleTagManager gtmId="GTM-XYZ" />
}

ارسال رویدادها Events

از تابع sendGTMEvent می‌توان برای ردیابی track تعاملات کاربر در صفحه‌ی شما با ارسال رویدادها با استفاده از آبجکت 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' })
				}
			>
				Send Event
			</button>
		</div>
	)
}

برای یادگیری متغیرها و رویدادهای مختلفی که می‌توان به تابع پاس داد، به مستندات توسعه‌دهنده‌ی Tag Manager (opens in a new tab) مراجعه کنید.

Options

گزینه‌هایی برای ارسال به Google Tag Manager. برای لیست کامل گزینه‌ها، اسناد Google Tag Manager (opens in a new tab) را مطالعه کنید.

نام	نوع	توضیحات
`gtmId`	اجباری	شناسه کانتینر GTM شما. معمولاً با `GTM-` شروع می‌شود.
`dataLayer`	اختیاری	آرایه لایه داده (data layer) برای ایجاد نمونه اولیه‌ی کانتینر. به صورت پیش فرض یک آرایه‌ی خالی است.
`dataLayerName`	اختیاری	نام لایه داده. به طور پیش‌فرض، `dataLayer` است.
`auth`	اختیاری	مقدار پارامتر احراز هویت (`gtm_auth`) برای قطعه کدهای محیطی.
`preview`	اختیاری	مقدار پارامتر پیش‌نمایش (gtm_preview) برای قطعه کدهای محیطی.

Google Analytics

از کامپوننت GoogleAnalytics برای افزودن Google Analytics 4 (opens in a new tab) به صفحه‌ی شما از طریق تگ گوگل (gtag.js) استفاده می‌شود. به طور پیش‌فرض، این کامپوننت اسکریپت‌های اصلی را پس از هیدراتاسیون صفحه فراخوانی می‌کند.

توصیه: اگر Google Tag Manager از قبل در برنامه‌ی شما گنجانده شده است، می‌توانید به جای استفاده از Google Analytics به عنوان یک کامپوننت جداگانه، آن را به طور مستقیم با استفاده از آن پیکربندی کنید. برای کسب اطلاعات بیشتر در مورد تفاوت‌های بین Tag Manager و gtag.js به مستندات (opens in a new tab) مراجعه کنید.

برای بارگذاری گوگل آنالیتیکس برای همه مسیرها، کامپوننت را مستقیماً در طرح بندی ریشه‌ی خود قرار دهید و ID اندازه‌گیری‌ی خود را وارد کنید:

app/layout.tsx

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

برای بارگذاری گوگل آنالیتیکس برای یک مسیر خاص، کامپوننت را در فایل page خود قرار دهید:

app/page.js

import { GoogleAnalytics } from '@next/third-parties/google'
 
export default function Page() {
	return <GoogleAnalytics gaId="G-XYZ" />
}

ارسال رویدادها Events

از تابع 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' })
				}
			>
				Send Event
			</button>
		</div>
	)
}

برای یادگیری بیشتر در مورد پارامترهای رویداد، به مستندات توسعه‌دهنده‌ی Google Analytics (opens in a new tab) مراجعه کنید.

ردیابی بازدیدهای صفحه

گوگل آنالیتیکس به طور خودکار بازدیدهای صفحه را زمانی که وضعیت تاریخچه‌ی مرورگر تغییر می‌کند، ردیابی می‌کند. این به این معنی است که پیمایش‌های سمت کلاینت بین مسیرهای Next.js بدون هیچ پیکربندی‌ای، داده‌های بازدید از صفحه را ارسال می‌کند.

برای اطمینان از اندازه‌گیری صحیح پیمایش‌های سمت کلاینت، تأیید کنید که ویژگی بهبود اندازه‌گیری “Enhanced Measurement” (opens in a new tab) در پنل مدیریت شما فعال باشد و کادر تأیید “Page changes based on browser history events” انتخاب شده باشد.

نکته: اگر تصمیم گرفتید رویدادهای بازدید از صفحه را به صورت دستی ارسال کنید، مطمئن شوید اندازه‌گیری پیش‌فرض بازدید از صفحه را غیرفعال کنید تا از داشتن داده‌های تکراری جلوگیری کنید. برای کسب اطلاعات بیشتر به مستندات توسعه‌دهنده‌ی Google Analytics (opens in a new tab) مراجعه کنید.

Options

گزینه‌هایی برای ارسال به کامپوننت <GoogleAnalytics>.

نام	نوع	توضیحات
`gaId`	اجباری	شناسه اندازه‌گیری (opens in a new tab) شما. معمولاً با `G-` شروع می‌شود.
`dataLayerName`	اختیاری	نام لایه داده. به طور پیش‌فرض، `dataLayer` است.

Google Maps Embed

از کامپوننت GoogleMapsEmbed می‌توان برای افزودن Google Maps Embed (opens in a new tab) به صفحه‌ی شما استفاده کرد. به طور پیش‌فرض، این کامپوننت از ویژگی loading برای بارگذاری بهینه (lazy-load) نقشه در قسمت‌های پایین‌تر صفحه استفاده می‌کند.

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"
		/>
	)
}

گزینه‌ها

گزینه‌هایی برای ارسال به کامپوننت GoogleMapsEmbed. برای لیست کامل گزینه‌ها، اسناد Google Map Embed (opens in a new tab) را مطالعه کنید.

Name	Type	Description
`apiKey`	اجباری	Your api key.
`mode`	اجباری	Map mode (opens in a new tab)
`height`	اختیاری	Height of the embed. Defaults to `auto`.
`width`	اختیاری	Width of the embed. Defaults to `auto`.
`style`	اختیاری	Pass styles to the iframe.
`allowfullscreen`	اختیاری	Property to allow certain map parts to go full screen.
`loading`	اختیاری	Defaults to lazy. Consider changing if you know your embed will be above the fold.
`q`	اختیاری	Defines map marker location. This may be required depending on the map mode.
`center`	اختیاری	Defines the center of the map view.
`zoom`	اختیاری	Sets initial zoom level of the map.
`maptype`	اختیاری	Defines type of map tiles to load.
`language`	اختیاری	Defines the language to use for UI elements and for the display of labels on map tiles.
`region`	اختیاری	Defines the appropriate borders and labels to display, based on geo-political sensitivities.

YouTube Embed

از کامپوننت YouTubeEmbed می‌توان برای بارگذاری و نمایش یک بافرگذاری embed یوتیوب استفاده کرد. این کامپوننت با استفاده از lite-youtube-embed (opens in a new tab) در هسته خود، سریع‌تر بارگذاری می‌شود.

app/page.js

import { YouTubeEmbed } from '@next/third-parties/google'
 
export default function Page() {
	return (
		<YouTubeEmbed videoid="ogfYd705cRs" height={400} params="controls=0" />
	)
}

گزینه‌ها

Name	Type	Description
`videoid`	اجباری	YouTube video id.
`width`	اختیاری	Width of the video container. Defaults to `auto`
`height`	اختیاری	Height of the video container. Defaults to `auto`
`playlabel`	اختیاری	A visually hidden label for the play button for accessibility.
`params`	اختیاری	The video player params defined here (opens in a new tab). Params are passed as a query param string. Eg: `params="controls=0&start=10&end=30"`
`style`	اختیاری	Used to apply styles to the video container.

دارایی های استاتیک استفاده از حافظه