diff --git a/docs/02-app/01-building-your-application/06-optimizing/10-third-party-libraries.mdx b/docs/02-app/01-building-your-application/06-optimizing/10-third-party-libraries.mdx index b82cce869d257..32567e6142e1c 100644 --- a/docs/02-app/01-building-your-application/06-optimizing/10-third-party-libraries.mdx +++ b/docs/02-app/01-building-your-application/06-optimizing/10-third-party-libraries.mdx @@ -162,9 +162,9 @@ export function EventButton() { -Refer to the [Tag Manager](https://developers.google.com/tag-platform/tag-manager/datalayer) -documentation to learn about the different variables and events that can be passed into the -function. +Refer to the Tag Manager [developer +documentation](https://developers.google.com/tag-platform/tag-manager/datalayer) to learn about the +different variables and events that can be passed into the function. #### Options @@ -179,6 +179,160 @@ docs](https://developers.google.com/tag-platform/tag-manager/datalayer). | `auth` | Optional | Value of authentication parameter (`gtm_auth`) for environment snippets. | | `preview` | Optional | Value of preview parameter (`gtm_preview`) for environment snippets. | +### Google Analytics + +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: + +```tsx filename="app/layout.tsx" switcher +import { GoogleAnalytics } from '@next/third-parties/google' + +export default function RootLayout({ + children, +}: { + children: React.ReactNode +}) { + return ( + + {children} + + + ) +} +``` + +```jsx filename="app/layout.js" switcher +import { GoogleAnalytics } from '@next/third-parties/google' + +export default function RootLayout({ children }) { + return ( + + {children} + + + ) +} +``` + + + + + +To load Google Analytics for all routes, include the component directly in your custom `_app`: + +```jsx filename="pages/_app.js" +import { GoogleAnalytics } from '@next/third-parties/google' + +export default function MyApp({ Component, pageProps }) { + return ( + <> + + + + ) +} +``` + + + +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 +} +``` + + + + + +```jsx filename="pages/index.js" +import { GoogleAnalytics } from '@next/third-parties/google' + +export default function Page() { + return +} +``` + + + +#### Sending Events + +The `sendGAEvent` function can be used to measure user interactions on your page by sending events +using the `dataLayer` object. For this function to work, the `` component must be +included in either a parent layout, page, or component, or directly in the same file. + + + +```jsx filename="app/page.js" +'use client' + +import { sendGAEvent } from '@next/third-parties/google' + +export function EventButton() { + return ( +
+ +
+ ) +} +``` + +
+ + + +```jsx filename="pages/index.js" +import { sendGAEvent } from '@next/third-parties/google' + +export function EventButton() { + return ( +
+ +
+ ) +} +``` + +
+ +Refer to the Google Analytics [developer +documentation](https://developers.google.com/analytics/devguides/collection/ga4/event-parameters) to learn +more about event parameters. + +#### Options + +Options to pass to the `` component. + +| Name | Type | Description | +| --------------- | -------- | ------------------------------------------------ | +| `gaId` | Required | Your Google tag id. | +| `dataLayerName` | Optional | Name of the data layer. Defaults to `dataLayer`. | + ### Google Maps Embed The `GoogleMapsEmbed` component can be used to add a [Google Maps