mirror of
https://github.com/vercel/next.js.git
synced 2026-09-20 02:25:18 +08:00
sam
7e093afb8c
Note: new PR description written by @timneutkens ## What? Improves the detection of Google Tag Manager vs Google Analytics. As indicated by the author of this PR it was confusing that when you have Google Tag Manager set up it gives you an error message saying you're adding Google Analytics even though it's Tag Manager. I've updated the PR to have a separate message for Google Tag Manager and expanded the error message docs too. It also mentioned `next/script` in a bunch of places even though the error doc recommends `@next/third-parties`. I've updated all cases to refer to `@next/third-parties` instead. <details> <summary>Previous PR description</summary> Google has multiple products with similar names: the "Google Tag" and "Google Tag Manager". Google Tag Manager uses `gtm.js` whereas the "Google Tag" uses `gtag`. Google Analytics previously used `analytics.js` (<2017) and is now delivered via the "Google Tag". Google Tag: `www.googletagmanager.com/gtag/js` Google Tag Manager: `www.googletagmanager.com/gtm.js` The `next-script-for-ga.ts` rule's matching list (`SUPPORTED_HTML_CONTENT_URLS`) includes `gtm.js` which means when a developer adds Google Tag Manager to their NextJS website, they'll receive the warning and be encouraged to swap from `gtm.js` to `gtag`. A developer asleep at the wheel (...me) may think... > I'm using Google Analytics via Google Tag Manager, and NextJS is suggesting I swap `gtm.js` for `gtag` because it will improve performance. `gtag` sounds like it is part of "Google Tag Manager" so I am going to follow the instructions so that my website is faster. However, `gtag` is **not** compatible with `gtm.js` (they're different products with similar names and similar purposes) and so making this change will cause very confusing Google Tag Manager behaviour. I am suggesting that `gtm.js` is removed completely from the rule, because anyone using `gtm.js` should not be following these instructions. A separate rule could be added specifically for Google Tag Manager, that does not refer to `gtag`. </details> --------- Co-authored-by: Tim Neutkens <tim@timneutkens.nl>
107 lines
3.7 KiB
Plaintext
107 lines
3.7 KiB
Plaintext
---
|
|
title: Using Google Analytics with Next.js (through `@next/third-parties/google`)
|
|
---
|
|
|
|
> Prefer `@next/third-parties/google` when using the inline script for Google Analytics and Tag Manager.
|
|
|
|
## Why This Error Occurred
|
|
|
|
An inline script was used for Google Analytics which might impact your webpage's performance. Instead, we recommend using `next/script` through the `@next/third-parties` library.
|
|
|
|
## Possible Ways to Fix It
|
|
|
|
### Use `@next/third-parties` to add Google Analytics
|
|
|
|
**`@next/third-parties`** is a library that provides a collection of components and utilities that improve the performance and developer experience of loading popular third-party libraries in your Next.js application. It is available with Next.js 14 (install `next@latest`).
|
|
|
|
The `GoogleAnalytics` component can be used to include [Google Analytics
|
|
4](https://developers.google.com/analytics/devguides/collection/ga4) to your page via the Google tag (`gtag.js`). By default, it fetches the original scripts after hydration occurs on the page.
|
|
|
|
> **Recommendation**: If Google Tag Manager is already included in your application, you can
|
|
> configure Google Analytics directly using it, rather than including Google Analytics as a separate component. Refer to the [documentation](https://developers.google.com/analytics/devguides/collection/ga4/tag-options#what-is-gtm)
|
|
> to learn more about the differences between Tag Manager and `gtag.js`.
|
|
|
|
To load Google Analytics for all routes, include the component directly in your root layout and pass in your measurement ID:
|
|
|
|
```tsx filename="app/layout.tsx" switcher
|
|
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>
|
|
)
|
|
}
|
|
```
|
|
|
|
```jsx filename="app/layout.js" switcher
|
|
import { GoogleAnalytics } from '@next/third-parties/google'
|
|
|
|
export default function RootLayout({ children }) {
|
|
return (
|
|
<html lang="en">
|
|
<body>{children}</body>
|
|
<GoogleAnalytics gaId="G-XYZ" />
|
|
</html>
|
|
)
|
|
}
|
|
```
|
|
|
|
To load Google Analytics for a single route, include the component in your page file:
|
|
|
|
```jsx filename="app/page.js"
|
|
import { GoogleAnalytics } from '@next/third-parties/google'
|
|
|
|
export default function Page() {
|
|
return <GoogleAnalytics gaId="G-XYZ" />
|
|
}
|
|
```
|
|
|
|
### Use `@next/third-parties` to add Google Tag Manager
|
|
|
|
The `GoogleTagManager` component can be used to add [Google Tag Manager](https://developers.google.com/tag-manager/quickstart) to your page.
|
|
|
|
```tsx filename="app/layout.tsx" switcher
|
|
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>
|
|
)
|
|
}
|
|
```
|
|
|
|
To load Google Tag Manager for a single route, include the component in your page file:
|
|
|
|
```jsx filename="app/page.js"
|
|
import { GoogleTagManager } from '@next/third-parties/google'
|
|
|
|
export default function Page() {
|
|
return <GoogleTagManager gtmId="GTM-XYZ" />
|
|
}
|
|
```
|
|
|
|
## Good to know
|
|
|
|
- If you are using the Pages Router, please refer to the [`pages/` documentation](/docs/pages/guides/third-party-libraries).
|
|
- `@next/third-parties` also supports [other third parties](/docs/app/guides/third-party-libraries#google-tag-manager).
|
|
- Using `@next/third-parties` is not required. You can also use the `next/script` component directly. Refer to the [`next/script` documentation](/docs/app/guides/scripts) to learn more.
|
|
|
|
## Useful Links
|
|
|
|
- [`@next/third-parties` Documentation](/docs/app/guides/third-party-libraries)
|
|
- [`next/script` Documentation](/docs/app/guides/scripts)
|