[Docs] Includes section to @next/third-parties documentation for Go…

…ogle Analytics (#59671)
vercel · Dec 19, 2023 · 25e0988 · 25e0988
1 parent a65fb16
commit 25e0988
Showing 1 changed file with 157 additions and 3 deletions.
diff --git a/.../02-app/01-building-your-application/06-optimizing/10-third-party-libraries.mdx b/.../02-app/01-building-your-application/06-optimizing/10-third-party-libraries.mdx
@@ -162,9 +162,9 @@ export function EventButton() {
 
 </PagesOnly>
 
-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`.
+
+<AppOnly>
+
+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 (
+    <html lang="en">
+      <body>{children}</body>
+      <GoogleAnalytics gaId="GA-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="GA-XYZ" />
+    </html>
+  )
+}
+```
+
+</AppOnly>
+
+<PagesOnly>
+
+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 (
+    <>
+      <Component {...pageProps} />
+      <GoogleAnalytics gaId="GA-XYZ" />
+    </>
+  )
+}
+```
+
+</PagesOnly>
+
+To load Google Analytics for a single route, include the component in your page file:
+
+<AppOnly>
+
+```jsx filename="app/page.js"
+import { GoogleAnalytics } from '@next/third-parties/google'
+
+export default function Page() {
+  return <GoogleAnalytics gaId="GA-XYZ" />
+}
+```
+
+</AppOnly>
+
+<PagesOnly>
+
+```jsx filename="pages/index.js"
+import { GoogleAnalytics } from '@next/third-parties/google'
+
+export default function Page() {
+  return <GoogleAnalytics gaId="GA-XYZ" />
+}
+```
+
+</PagesOnly>
+
+#### 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 `<GoogleAnalytics />` component must be
+included in either a parent layout, page, or component, or directly in the same file.
+
+<AppOnly>
+
+```jsx filename="app/page.js"
+'use client'
+
+import { sendGAEvent } from '@next/third-parties/google'
+
+export function EventButton() {
+  return (
+    <div>
+      <button
+        onClick={() => sendGAEvent({ event: 'buttonClicked', value: 'xyz' })}
+      >
+        Send Event
+      </button>
+    </div>
+  )
+}
+```
+
+</AppOnly>
+
+<PagesOnly>
+
+```jsx filename="pages/index.js"
+import { sendGAEvent } from '@next/third-parties/google'
+
+export function EventButton() {
+  return (
+    <div>
+      <button
+        onClick={() => sendGAEvent({ event: 'buttonClicked', value: 'xyz' })}
+      >
+        Send Event
+      </button>
+    </div>
+  )
+}
+```
+
+</PagesOnly>
+
+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 `<GoogleAnalytics>` 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