Сторонние библиотеки

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

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

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

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

Терминал

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

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

Сторонние библиотеки Google

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

Google Tag Manager

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

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

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

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

Обратитесь к документации разработчика Tag Manager, чтобы узнать о различных переменных и событиях, которые можно передать в функцию.

Параметры

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

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

Google Analytics

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

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

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

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

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

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

Обратитесь к документации разработчика Google Analytics, чтобы узнать больше о параметрах событий.

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

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

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

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

Параметры

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

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

Google Maps Embed

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

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

Параметры

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

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

YouTube Embed

Компонент YouTubeEmbed можно использовать для загрузки и отображения встраиваемого контента YouTube. Этот компонент загружается быстрее благодаря использованию 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`	Обязательный	Идентификатор видео YouTube.
`width`	Опциональный	Ширина контейнера видео. По умолчанию `auto`
`height`	Опциональный	Высота контейнера видео. По умолчанию `auto`
`playlabel`	Опциональный	Скрытая метка для кнопки воспроизведения для доступности.
`params`	Опциональный	Параметры видеоплеера, определённые здесь. Параметры передаются в виде строки запроса. Например: `params="controls=0&start=10&end=30"`
`style`	Опциональный	Используется для применения стилей к контейнеру видео.

Сторонние библиотеки

On this page