Библиотеки сторонних разработчиков

@next/third-parties — это библиотека, предоставляющая набор компонентов и утилит, которые улучшают производительность и опыт разработчиков при загрузке популярных библиотек сторонних разработчиков в вашем приложении Next.js.

Все интеграции сторонних разработчиков, предоставляемые @next/third-parties, оптимизированы для производительности и удобства использования.

Начало работы

Для начала работы, установите библиотеку @next/third-parties:

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

В настоящее время библиотека @next/third-parties находится на стадии активного развития в качестве экспериментальной. Мы рекомендуем устанавливать её с использованием последних или экспериментальных версий, пока мы работаем над добавлением большего количества интеграций сторонних разработчиков.

Библиотеки сторонних разработчиков Google

Все поддерживаемые библиотеки сторонних разработчиков Google можно импортировать из @next/third-parties/google.

Google Tag Manager

Компонент GoogleTagManager можно использовать для инициализации контейнера Google Tag Manager на вашей странице. По умолчанию он извлекает исходный встроенный скрипт после завершения процесса гидратации страницы.

Чтобы загрузить Google Tag Manager для всех маршрутов, добавьте компонент непосредственно в файл root layout и передайте свой идентификатор контейнера 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>
  )
}

Чтобы загрузить Google Tag Manager для отдельного маршрута, добавьте компонент в файл вашей страницы:

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

Отправка событий

Функция sendGTMEvent может использоваться для отслеживания взаимодействия пользователей на вашей странице, отправляя события с помощью объекта dataLayer. Для работы этой функции компонент <GoogleTagManager /> должен быть включён либо в родительском макете, на странице или в компоненте, либо непосредственно в том же файле.

'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, чтобы узнать о различных переменных и событиях, которые можно передавать в функцию.

Параметры

Параметры для передачи в Google Tag Manager. Полный список параметров см. в документации Google Tag Manager.

Имя	Тип	Описание
`gtmId`	Обязательный	Ваш идентификатор контейнера GTM. Обычно начинается с `GTM-`.
`dataLayer`	Необязательный	Массив данных слоя для инициализации контейнера. По умолчанию пустой массив.
`dataLayerName`	Необязательный	Имя слоя данных. По умолчанию `dataLayer`.
`auth`	Необязательный	Значение параметра аутентификации (`gtm_auth`) для фрагментов среды.
`preview`	Необязательный	Значение параметра предварительного просмотра (`gtm_preview`) для фрагментов среды.

Google Analytics

Компонент GoogleAnalytics можно использовать для включения Google Analytics 4 на вашей странице через тег Google (gtag.js). По умолчанию он извлекает исходные скрипты после гидрации страницы.

Рекомендация: Если Google Tag Manager уже включён в ваше приложение, вы можете настроить Google Analytics непосредственно с помощью него, вместо включения Google Analytics как отдельного компонента. Обратитесь к документации, чтобы узнать больше о различиях между Tag Manager и gtag.js.

Чтобы загрузить Google Analytics для всех маршрутов, добавьте компонент непосредственно в свой root layout и передайте свой идентификатор измерения:

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

Чтобы загрузить Google Analytics для отдельного маршрута, добавьте компонент в файл вашей страницы:

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

Отправка событий

Функция sendGAEvent может использоваться для измерения взаимодействия пользователей на вашей странице, отправляя события с помощью объекта dataLayer. Для работы этой функции компонент <GoogleAnalytics /> должен быть включён либо в родительском макете, на странице или в компоненте, либо непосредственно в том же файле.

'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, чтобы узнать больше о параметрах событий.

Отслеживание просмотров страниц

Google Analytics автоматически отслеживает просмотры страниц при изменении состояния истории браузера. Это означает, что переходы по маршрутам Next.js с клиентской стороны будут отправлять данные о просмотрах страниц без каких-либо настроек.

Чтобы убедиться, что переходы с клиентской стороны измеряются правильно, проверьте, что свойство «Расширенное измерение» включено в вашем административном панели и что выбран чекбокс «Изменения страниц на основе событий истории браузера».

Примечание: Если вы решите вручную отправлять события просмотров страниц, убедитесь, что отключено автоматическое измерение просмотров страниц, чтобы избежать дублирования данных. Обратитесь к документации разработчика Google Analytics, чтобы узнать больше.

Параметры

Параметры для передачи компоненту <GoogleAnalytics>.

Имя	Тип	Описание
`gaId`	Обязательный	Ваш идентификатор измерения. Обычно начинается с `G-`.
`dataLayerName`	Необязательный	Имя слоя данных. По умолчанию `dataLayer`.

Вставка Google Карт

Компонент GoogleMapsEmbed можно использовать для добавления Google Карт на вашу страницу. По умолчанию он использует атрибут loading для отложенной загрузки вставки под складкой.

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

Параметры

Параметры для передачи в компонент вставки Google Карт. Полный список параметров см. в документации Google Карт.

Имя	Тип	Описание
`apiKey`	Обязательный	Ваш ключ API.
`mode`	Обязательный	Режим карты
`height`	Необязательный	Высота вставки. По умолчанию `auto`.
`width`	Необязательный	Ширина вставки. По умолчанию `auto`.
`style`	Необязательный	Передача стилей во фрейм.
`allowfullscreen`	Необязательный	Свойство для разрешения отображения некоторых частей карты во весь экран.
`loading`	Необязательный	По умолчанию отложенная загрузка. Рассмотрите возможность изменения, если вы знаете, что ваша вставка будет выше складки.
`q`	Необязательный	Определяет расположение маркера на карте. Это может потребоваться в зависимости от режима карты.
`center`	Необязательный	Определяет центр области просмотра карты.
`zoom`	Необязательный	Устанавливает начальный уровень масштабирования карты.
`maptype`	Необязательный	Определяет тип плиток карты для загрузки.
`language`	Необязательный	Определяет язык для элементов интерфейса и отображения меток на плитках карты.
`region`	Необязательный	Определяет соответствующие границы и метки для отображения, основанные на геополитических нюансах.

Вставка YouTube

Компонент YouTubeEmbed можно использовать для загрузки и отображения вставки YouTube. Этот компонент загружается быстрее, используя lite-youtube-embed под капотом.

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

Параметры

Имя	Тип	Описание
`videoid`	Обязательный	Идентификатор видео YouTube.
`width`	Необязательный	Ширина контейнера видео. По умолчанию `auto`
`height`	Необязательный	Высота контейнера видео. По умолчанию `auto`
`playlabel`	Необязательный	Визуально скрытая метка для кнопки воспроизведения для обеспечения доступности.
`params`	Необязательный	Параметры видеоплеера, определённые здесь. Параметры передаются как строка запроса. Пример: `params="controls=0&start=10&end=30"`
`style`	Необязательный	Используется для применения стилей к контейнеру видео.

© 2024 Vercel, Inc.
Licensed under the MIT License.
https://nextjs.org/docs/app/building-your-application/optimizing/third-party-libraries