Merge pull request #6262 from segmentio/doc-840_GA4

adding changes to GA4 topics

Author: forstisabella

src/connections/destinations/catalog/actions-google-analytics-4-web/ga4-faq-and-troubleshooting

@@ -0,0 +1,85 @@
+---
+title: Google Analytics 4 FAQ and Troubleshooting
+strat: google
+---
+
+## Debug mode
+
+The Google Analytics 4 debug mode, [DebugView](https://support.google.com/analytics/answer/7201382?hl=en){:target="_blank"} is supported with the Google Analytics 4 Web destination. DebugView displays the events and user properties that Analytics collects from a user in real-time. This can be helpful when troubleshooting your implementation.
+
+## Send events from both the browser and the server 
+
+With Google Analytics 4 Web, events are sent from the browser (client-side) to GA4. If you use Segment’s [Google Analytics 4 Cloud destination](/docs/connections/destinations/catalog/actions-google-analytics-4/#benefits-of-google-analytics-4-cloud) to send events through the Measurement Protocol API and want to tie data between client-side and server-side, you need to pass the same Client ID from the browser and the server for GA4 to merge events around a distinct user, and if you want the server-side event to be tied to the client-side session, you must pass the session_id in the server side event.
+
+The client_id and the session_id are both cookies stored in the user browser. You can use [Google gtag get commands](https://developers.google.com/tag-platform/gtagjs/reference#get){:target=”_blank”} or other cookie methods to parse these values from the _ga cookie and _ga_measurementId cookie:
+- If your _ga cookie is GA1.1.1783165678.1701112990 then 1783165678.1701112990 is your client_id
+- If your _ga_M12454XDR cookie is GS1.1.1710342977.347.1.1710343074.0.0.0 then 1710342977 is your session_id
+
+You are not required to send a session number for server-side hits. Session metrics come from the client-side data after GA4 stitches server-side event data to the client-side session.
+
+> success ""
+> Segment recommends that you enable the GA4 Web destination first then incorporate GA4 Cloud destination to augment your client-side tracking, as a hybrid GA4 application is an advanced implementation. Segment also recommends that you have deep knowledge of GA4 session-stitching, troubleshooting, and known caveats of the GA4 Measurement Protocol prior to implementing the Google Analytics 4 destination.
+
+## Additional (unmapped) events are sent to GA4
+
+Google Analytics 4 collects events triggered by basic interactions with your site. For more information about which interactions are automatically collected, see [Google Analytics 4 Automatically Collected events](https://support.google.com/analytics/answer/9234069?hl=en){:target="_blank"}.
+
+## Data takes a long time to appear in Google's reports
+
+Google may take [24-48 hours](https://support.google.com/analytics/answer/9333790){:target="_blank"} to process data sent to Google Analytics. As a result, the Google Analytics user interface may not reflect the most current data. The Google Analytics [Realtime report](https://support.google.com/analytics/answer/9271392){:target="_blank"} displays activity on your site as it happens; however, events seen in Realtime reports do not always equate to how the data is processed in the standard reports. This disconnect between events seen in Realtime reports and Standard reports happens when a Custom Definition is not defined in the GA4 Admin panel.
+
+## Data is not sent to Google
+
+For event data to be sent downstream to Google Analytics:
+
+1. Configure and enable the  **Set Configuration Fields** mapping. This mapping is required for data to be sent downstream because it sets configuration to the GA4 Measurement ID indicated in the Settings and establishes data flow using the `config` command.
+2. Confirm you call `analytics.page()` on page load. Analytics.js requires an initial Page call to send data to Google Analytics 4 Web. _The Segment snippet includes this initial call by default._
+3. Send data with an event: typically this is a `page_view` as your first event. 
+
+ > note "If you toggled Page Views in your Settings to “On”, the page_view event automatically sends when the Set Configuration Mapping is triggered"
+ > If you need to override this setting for your particular use case, see [Can I override my send_page_view selection that I declared in Settings?](#can-i-override-my-send_page_view-selection-that-i-declared-in-settings)
+
+If no events are flowing to your GA4 instance, use one of the Debugging Tools to check the sequence of GA4 events.
+
+## Duplicate `page_view` events in GA4
+
+If you are sending multiple `gtag(‘config’)` commands called from Set Configuration mapping on one page before a new DOM has loaded, and you have defined `send_page_view: true` with each ‘Config’ event, you may see duplicate `page_view` events sent to your GA4 measurement id. If this is the case, please refer to Google's documentation on [Ignoring duplicate instances of on-page configuration](https://support.google.com/analytics/answer/9973999?hl=en#:~:text=as%20described%20below.-,Ignore%20duplicate%20instances%20of%20on%2Dpage%20configuration,Click%20Save.,-Give%20feedback%20about){:target="_blank"}. 
+
+If your site is a Single Page Application (SPA), you may want to leave the **Ignore duplicate instances of on-page configuration** toggle disabled in the Google Tag Admin as a new DOM is not called on each new page path. If you have a SPA, disabled the **Ignore duplicate instances of on-page configuration** toggle, and have multiple Set Configuration mappings, use Segment's new **Send Page Views** field mapping to override the `send_page_view` parameter in your Settings. This selection takes precedence over what is defined in the Segment Settings. If you leave the selection for your destination undefined, it will fall back to what you selected in the Segment Settings.
+
+If you enabled Enhanced Measurement, you might see additional `page_view` events. This happens when you enable the **Page changes based on browser history events** feature in the Advanced settings section of the **pageviews** settings. To avoid double counting page views on history state changes, disable the **Page changes based on browser history events** feature. See Google's [Manual pageviews](https://developers.google.com/analytics/devguides/collection/ga4/views?client_type=gtag#manual_pageviews){:target="_blank"} documentation for more information.
+
+## Manually send `page_view` events
+
+If you prefer to keep the **Page Views** setting disabled and manually send `page_view` events, see Google's documentation, [Manually send `page_view` events](https://developers.google.com/analytics/devguides/collection/ga4/views?client_type=gtag#manually_send_page_view_events).
+
+With Google Analytics 4 Web, you must configure a [Custom Event](/docs/connections/destinations/catalog/actions-google-analytics-4-web/#custom-event) mapping to manually send `page_view` events. When mapping the events, set the Event Name to `page_view`.
+
+You can now override the send_page_view value defined in the Segment Settings for the GA4 destination. To override the `send_page_view` value, navigate to your Set Configuration Mapping, click “Show More Fields” to expose the field mapping, and select either True or False. This selection takes precedence over what is defined in the Segment Settings. If you leave this selection undefined, Segment uses the selection you made in the Segment Settings.
+
+### Tracking UTM Parameters
+
+Segment automatically tracks UTM parameters when they are present in the URL and sends them to Google. For example, with the following URL, Segment would send `email_variation1&utm_medium=email&utm_source=email_promo&utm_campaign=summer_sale&utm_id=abcd` to Google:
+`https://www.example.com/?utm_content=email_variation1&utm_medium=email&utm_source=email_promo&utm_campaign=summer_sale&utm_id=abcd`
+
+By default, if the UTM values are found in the `page_location` parameter, GA4 automatically maps the campaign parameters to their appropriate value. There is no additional configuration required, unless you want to override what GA4 defines. This is true for both Event mappings and the Set Configuration mapping. If you modify the output of the `page_location` and the UTM parameters are not included, this might result in erroneous acquisition and attribution mapping. 
+
+To observe this feature, trigger a `Page` call with UTM parameters present in the URL and navigate to the **Realtime overview** report in GA4 to see the resulting `page_view` event under the _Event count by Event name_ card. The Acquisition card in the Realtime overview report reflects First User acquisition, but may not reflect the parameters of the event if this was a second session event. 
+
+## Pass Custom Event parameters to all events and Custom Item parameters to all recommended Ecommerce events
+
+To pass custom event parameters to all events on the page, navigate to your Set Configuration Mapping, click Show All Fields, and enter any custom Event Parameters, including page_view. Any event parameters that have the same parameter key in Event Mappings will take precedence over what is set in the Set Configuration Mapping. 
+
+To send custom item parameters, add the custom item parameter name in mappings where there is a Products array. Register your custom item parameter in the GA4 Admin panel if you would like this value processed in the GA4 UI. You can ONLY add custom item parameters in the Products array. If you add custom item parameters as an Event Parameter, they will be registered as an Event Parameter.
+
+## My Events Send to the wrong Google ID
+
+In each Event Mapping, there is a “Send To” parameter. Set this to “True” if you would like to include the send_to parameter and only send the event to the measurement_id indicated in the settings. If you select “False” or do not enter a selection, GA4 Events will broadcast to all measurement IDs, including Google Ads IDs, on the page.
+
+## Can I override my send_page_view selection that I declared in the Settings?
+
+Yes. In the Set Configuration Mapping, click Show All Fields and scroll to Send Page Views. Your selection overrides what is set within the Settings. This is helpful if you are updating the user_id or user_properties for all events on the page where you want to call the config command but do not want to send a page_view.
+
+## Differences between the Google Analytics 4 Cloud and Google Analytics 4 Web destinations 
+
+Segment's [Google Analytics 4 Cloud](/docs/connections/destinations/catalog/actions-google-analytics-4/) server-side destination uses Google's Measurement Protocol API to send event data server to server, whereas Segment's [Google Analytics 4 Web](/docs/connections/destinations/catalog/actions-google-analytics-4-web/) device-mode destination loads the gtag.js library client-side and uses Segment's event data to map to gtag.js events directly. Each destination has its own advantages and disadvantages. Your choice between the two depends on your specific use case, technical expertise, and the platforms from which you want to track data.