[@next/third-parties/google-analytics] Add gaOptions argument to match gtag.js config functionality

[koji-koji]

Goals

1. The default parameters that can be configured with the config function in gtag.js cannot be set with the Google Analytics component in Third-Party Libraries
2. There is no option to set send_page_view to false, which is available in gtag.js.
3. The current documentation mentions the send_page_view option, but it is unclear how to configure it, so this needs to be addressed.

Non-Goals

1. This feature request does not aim to provide a complete overhaul or redesign of the Google Analytics component.
2. It does not include support for other Google Analytics features beyond what is available in the config function.

Background

Currently, the Google Analytics component in Next.js' Third-Party Library does not provide the functionality to set the send_page_view option to false or to configure the default parameters available in gtag.js's config function. This limitation can cause issues when users want to manually send pageview events but are unable to disable the default pageview tracking, potentially leading to duplicate data.

The Next.js documentation recommends disabling the default pageview measurement when manually sending pageview events. However, the current Google Analytics component does not offer a way to set send_page_view to false, resulting in a discrepancy between the documentation and the available functionality. Additionally, the link in the documentation appears to be broken, making it unclear for users on how to proceed.

In practice, the Google Analytics component currently only passes the config string and the gaId to the gtag function as arguments, without the option to include additional parameters required for more advanced configurations.

  return (
    <>
      <Script
        id="_next-ga-init"
        dangerouslySetInnerHTML={{
          __html: `
          window['${dataLayerName}'] = window['${dataLayerName}'] || [];
          function gtag(){window['${dataLayerName}'].push(arguments);}
          gtag('js', new Date());

          gtag('config', '${gaId}');`,
        }}
      />
      <Script
        id="_next-ga"
        src={`https://www.googletagmanager.com/gtag/js?id=${gaId}`}
      />
    </>

To disable send_page_view or configure default parameters, it is necessary to pass an additional third argument to the gtag function:

gtag('config', 'TAG_ID', {
  'send_page_view': false,
  'groups': 'agency'
});

Without the ability to pass this third argument, the Google Analytics component may not function adequately for certain use cases, such as when users need to prevent the default pageview event from being sent or apply specific configuration options. Therefore, it is desirable to allow configurations equivalent to those possible with gtag.js's config function to ensure that the component is flexible enough to meet these needs.

Proposal

To implement this feature, I propose adding a new argument called gaOptions to the GoogleAnalytics component in the packages/third-parties/src/google/ga.tsx file. This argument would allow users to pass custom configurations directly as the third parameter to the gtag function's config call.

Specifically, the code would be modified as follows:

export function GoogleAnalytics(props: GAParams) {
  const { gaId, gaOptions, dataLayerName = 'dataLayer' } = props;
  ...
  gtag('config', gaId, gaOptions);
}

As for the documentation, I suggest the following adjustments:

• Add Example: "If you want to set send_page_view to false or configure common parameters, you can do so by adding the gaOptions argument."
• Change Broken Link: Replace the outdated or broken link with the correct reference to Google Tag Platform Documentation.

Example:

<GoogleAnalytics
  gaId="YOUR_GA_ID"
  gaOptions={{ send_page_view: false, groups: 'agency' }}
/>

By updating the documentation in this way, users will have a clearer understanding of how to use the gaOptions argument to customize their Google Analytics setup.

I am eager to contribute to the implementation of this feature!

[cameronmolen]

@koji-koji I love this proposal! I implemented the GoogleAnalytics component into my application and quickly realized how limited the component is. I'm finding that I'll have to remove it and instead opt for using the Next Script component to make this component fit my needs. For my use-case, I need to be able to follow the path a single user takes across my site. It's very straightforward to add a user_id field to the GA4 script (see https://developers.google.com/analytics/devguides/collection/ga4/user-id), the GoogleAnalytics component just needs to be updated to handle it properly.

Is there any momentum to work on adding these features now?

[koji-koji]

@cameronmolen
Thank you for your comment!

I was worried that my proposal might not be appropriate since there hadn’t been any responses for a while, so I’m relieved to hear your feedback.

I agree with you about the need for improvements to the GoogleAnalytics component. I plan to work on adding the feature you suggested and will create a PR to propose it!

[cameronmolen]

I've been following a similar feature proposal that just got approved this morning. You might want to reference #63405 while you're working on your PR since it looks like this will be merged in soon.

[koji-koji]

Thank you for sharing this information! I will definitely reference #63405!

[koji-koji]

Sorry, the document link was not broken. I'm using the Brave browser, but it opened without issues in Chrome. However, the other issues still remain.

[jasonslyvia]

Great proposal! Just wondering before changes can be made, what will be the most appropriate way to pass gaOptions to window.gtag? Maybe adding an useEffect in the layout.tsx trying to access it?

[koji-koji]

Thank you! Regarding your question, yes, if the gaOptions need to be dynamic, using useEffect in layout.tsx would be appropriate to access and update them. However, if the options are static, I think it should be fine to pass them directly without useEffect.