第三方库

@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 标签管理器

GoogleTagManager 组件可用于在页面实例化 Google 标签管理器容器。默认情况下，它会在页面完成水合后获取原始内联脚本。

要为所有路由加载 Google 标签管理器，请直接将组件包含在根布局中并传入您的 GTM 容器 ID：

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 标签管理器，请将组件包含在页面文件中：

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

参阅标签管理器的开发者文档了解可传入函数的不同变量和事件。

选项

传递给 Google 标签管理器的选项。完整选项列表请阅读 Google 标签管理器文档。

名称	类型	描述
`gtmId`	必填	您的 GTM 容器 ID。通常以 `GTM-` 开头。
`dataLayer`	可选	用于实例化容器的数据层数组。默认为空数组。
`dataLayerName`	可选	数据层名称。默认为 `dataLayer`。
`auth`	可选	环境代码片段的认证参数值 (`gtm_auth`)。
`preview`	可选	环境代码片段的预览参数值 (`gtm_preview`)。

Google 分析

GoogleAnalytics 组件可用于通过 Google 标签 (gtag.js) 将 Google Analytics 4 包含到页面中。默认情况下，它会在页面完成水合后获取原始脚本。

推荐：如果应用中已包含 Google 标签管理器，可以直接通过它配置 Google Analytics，而无需单独包含 Google Analytics 组件。参阅文档了解标签管理器与 gtag.js 的区别。

要为所有路由加载 Google 分析，请直接将组件包含在根布局中并传入您的测量 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>
  )
}

要为单个路由加载 Google 分析，请将组件包含在页面文件中：

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 分析的开发者文档了解事件参数详情。

追踪页面浏览

当浏览器历史状态变化时，Google 分析会自动追踪页面浏览。这意味着 Next.js 路由间的客户端导航将在无需配置的情况下发送页面浏览数据。

为确保正确测量客户端导航，请验证您的管理面板中是否启用了"增强测量"属性，并选中了_"基于浏览器历史事件的页面变化_"复选框。

注意：如果决定手动发送页面浏览事件，请确保禁用默认的页面浏览测量以避免数据重复。参阅 Google 分析的开发者文档了解更多。

选项

传递给 <GoogleAnalytics> 组件的选项。

名称	类型	描述
`gaId`	必填	您的测量 ID。通常以 `G-` 开头。
`dataLayerName`	可选	数据层名称。默认为 `dataLayer`。

Google 地图嵌入

GoogleMapsEmbed 组件可用于将 Google 地图嵌入添加到页面。默认情况下，它使用 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 地图嵌入的选项。完整选项列表请阅读 Google 地图嵌入文档。

名称	类型	描述
`apiKey`	必填	您的 API 密钥。
`mode`	必填	地图模式
`height`	可选	嵌入高度。默认为 `auto`。
`width`	可选	嵌入宽度。默认为 `auto`。
`style`	可选	传递给 iframe 的样式。
`allowfullscreen`	可选	允许地图部分区域全屏显示的属性。
`loading`	可选	默认为懒加载。如果确定嵌入会出现在首屏，可考虑修改。
`q`	可选	定义地图标记位置。_根据地

On this page