Оптимизация сторонних библиотек

@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, пока мы работаем над добавлением новых сторонних интеграций.

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

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

Google Tag Manager

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

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

Серверная разметка

Если вы используете серверный менеджер тегов и обслуживаете скрипты gtm.js с вашего сервера тегов, вы можете использовать опцию gtmScriptUrl для указания URL скрипта.

Опции

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

Имя	Тип	Описание
`gtmId`	Обязательно	ID вашего контейнера GTM. Обычно начинается с `GTM-`.
`gtmScriptUrl`	Опционально	URL скрипта GTM. По умолчанию `https://www.googletagmanager.com/gtm.js`.
`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 напрямую через него, вместо использования отдельного компонента Google Analytics. Подробнее о различиях между Tag Manager и gtag.js см. в документации.

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

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 будут отправлять данные о просмотрах без дополнительной настройки.

Чтобы убедиться, что клиентские переходы корректно измеряются, проверьте, что в панели администратора включено свойство "Enhanced Measurement" и выбрана галочка "Page changes based on browser history events".

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

Опции

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

Имя	Тип	Описание
`gaId`	Обязательно	Ваш measurement ID. Обычно начинается с `G-`.
`dataLayerName`	Опционально	Имя data layer. По умолчанию `dataLayer`.
`nonce`	Опционально	Nonce.

Встраивание Google Maps

Компонент 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. Полный список опций см. в документации.

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

Встраивание YouTube

Компонент 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