Google Analytics 4 Proxy Reference

This is a Proxy Integration for GA4. This destination runs on Freshpaint's servers, but emulates a native installation of GA4. That means the integration behaves the same as if you did a native installation of GA4, but the data first flows through Freshpaint before it's sent to GA4. See our docs on proxy integrations for more information.

Google Analytics 4 is an analytics service that enables you to measure traffic and engagement across your websites and apps.

After sending Freshpaint data to Google Analytics 4, you'll be able to analyze the data in order to identify trends and patterns in how visitors engage with your website(s).

Learn more about Google Analytics 4 here.

Destination Info

• Accepts Track and Identify calls

• Refer to this destination as Google Analytics 4 Proxy in the Integrations object

  • If you've configured multiple Measurement IDs, you can choose a specific one by suffixing the Measurement ID, such as: Google Analytics 4 Proxy::G-PSW1MY7HB4. You can retrieve this value from the Google Analytics 4 (Proxy) configuration page for the Measurement ID of interest.

  • For other considerations when using multiple Google Analytics 4 Proxy Measurement IDs, see Google Analytics 4 Proxy Advanced Tracking Configurations.

When no suffix is specified, all configured Measurement IDs are selected for inclusion / exclusion.

• Connection Modes:

	Client-side	Server-side (Proxy)
Web
Mobile
Server

Events

All events will be sent to GA4 from Freshpaint's servers. Your website will not send data directly to GA4. Instead, your website and all other sources will send data to Freshpaint, which is translated then sent to GA4.

Events sent from Freshpaint to GA4 will show up as standard GA4 events. From there you can use your events in any of the GA4 reports and use it to generate insights into your business.

Page View Events

Freshpaint will automatically send a page_view event to Google Analytics. This page view event will behave the same as the native Google Analytics page_view event.

Manually sending a page view event to Freshpaint by calling freshpaint.page() is not currently supported.

If you have a requirement to have more granular control of which page views should be sent to GA4, you can choose to disable the Send Page View option and create a custompage_view event that only triggers on the pages you want to send to GA4 instead.

Session Start

Freshpaint will automatically send a session_start event to Google Analytics. A new session is created for a user if the user performs an action after 30 minutes of inactivity.

Engagement Time

Freshpaint will automatically send engagement time to GA4 and populate the engagement time reports in GA4.

Seeing user engagement discrepancies from a native GA4 implementation? See the article here for more information on this topic.

Scroll

Freshpaint will automatically scroll events to GA4.

Video Engagement

Freshpaint can be optionally enabled to send video_start, video_progress, and video_complete events to GA4. This includes videos hosted on Freshpaint's Video Platform.

Enable the Send Video Engagement Event option in the GA4 destination Base Configuration settings to turn on sending Video events to GA4. The recommended property $video_event_type must be allowlisted for video engagement events to be forwarded. Additionally, you can also allowlist these contextual video properties: video_current_time, video_duration, video_percent, video_provider, video_title, and video_url.

The current version of Freshpaint will only track video progress on YouTube videos embedded on a page using the YouTube JavaScript API or Freshpaint Video Platform videos embedded as IFrames. Other video providers may be supported in the future.

Conversions

Freshpaint is able to send conversion events to GA4. For this to work, there are two necessary steps:

1. Using an existing event, or after creating a new event, you must mark that event as a conversion in GA4's dashboard.

2. You must include a property named "conversion" and set it to true in your event. You can do this with a direct call to freshpaint.track(), or you can do this as a transformation. If you're using the Google Tag Manager Integration, you should set the conversion property on the Freshpaint GA4 tag.

If your account is in HIPAA mode, then you must add conversion to your HIPAA allowlist, unhashed. If you don't allow conversion, then GA4 will not be able to see the property it needs to consider your event a conversion.

You can find the interface in GA4 that lets you mark events as conversions at Admin > Events, where the link is below the property you're looking to measure events:

In this example, the last two events shown are marked as conversions

Below is also an example of what a transformation would look like to send the conversion property to GA4 as a constant property:

Purchases

You can send purchase events to GA4. Here is GA4's reference documentation: https://developers.google.com/analytics/devguides/collection/ga4/reference/events?client_type=gtag#purchase

From the Freshpaint side, there are a few things you need to know:

Your event name must be purchase. You can either create an event named purchase, or you can use a transformation to change some other event's name to to purchase when sent to the GA4 Proxy destination.

You must include two properties named currency and value. currency should be a three letter currency code - for example, USD for US dollar. value should be a number which is the purchase price.

Finally, you must include a property named items, which is an array of objects that contains properties like the following. Some of these properties are required; if you don't include them, your event may not be recorded as a purchase by GA4.

Item Property	Required?	Description
item_id		The product ID
item_name		The name of the product
price		How much the item costs according to the currency used
quantity		How many of the item was purchased
item_brand		The brand of the item
item_category		The category of the item. If used as part of a category hierarchy or taxonomy then this will be the first category.
item_category2		The second category hierarchy or additional taxonomy for the item.
item_category3		The third category hierarchy or additional taxonomy for the item.
item_category4		The fourth category hierarchy or additional taxonomy for the item.
item_category5		The fifth category hierarchy or additional taxonomy for the item.
item_variant		The item variant or unique code or description for additional item details/options.
affiliation		A product affiliation to designate a supplying company or brick and mortar store location.
discount		The monetary discount value associated with the item.
coupon		A coupon code, if one was used
item_list_id		The ID of the list in which the item was presented to the user.
item_list_name		The name of the list in which the item was presented to the user.
index		The index/position of the item in a list.
location_id		The physical location associated with the item (e.g. the physical store location). It's recommended to use the Google Place ID that corresponds to the associated item. A custom location ID can also be used.
creative_name		The name of a promotional creative
creative_slot		The name of the promotional creative slot associated with the item.
promotion_id		The ID of the promotion associated with the item.
promotion_name		The name of the promotion associated with the item.

Here's an example event payload that would send a purchase event:

{
  "token": "<your-env-id>",
  "time": 1680551282,
  "$device_id": "test-device-id",
  "currency": "USD",
  "value": 123.45,
  "items": [{
    "item_id":       "item 1",
    "item_name":     "my-name",
    "item_brand":    "blammo",
    "item_category": "cool products",
    "item_variant":  "tie-dye",
    "price":    123.45,
    "quantity": 3,
    "coupon":   "WINTER_FUN",
    "item_list_name":     "fun list",
    "index": 1,
    "creative_name": "spring sale 1"
  }, {
    "item_id":       "item 2",
    "item_name":     "my-name 2",
    "item_brand":    "blammo",
    "item_category": "cool products",
    "item_variant":  "tie-dye",
    "price":    15,
    "quantity": 1,
    "coupon":   "WINTER_FUN",
    "item_list_name":     "fun list",
    "index": 2,
    "creative_name": "spring sale 2"
  }],
}

Identify

An identify call will show up in Google as an "Identify" event. Any user properties sent in the identify call will show up as user properties in Google Analytics.

If HIPAA mode is enabled for your account, Freshpaint will redact URL paths by default. To avoid seeing /url-redacted-by-freshpaint URL paths in GA4 reporting, you will need to allowlist the URL property under User Properties for Identify events.

Testing your events

While Google Analytics 4 normally requires you to wait for the next day to see your data shown in reports, it offers a way to quickly test your events in real time. To do that, first head to your account's admin screen, and then click DebugView:

That link takes you to a screen where debug events show up in a real time. To send debug events to GA4, you need to add a property to your events named "debug_mode" set to true. Here's an example:

{
  "distinct_id": "test-user-id",
  "$device_id": "111222",
  "token": "your-environment-id",
  "time": 1680131903,
  "debug_mode": true,
  "test-property": 10
}

You can, for example, send such an event with our Event Tester. When you submit your event, it will now show up in the DebugView.

Select a device from the Debug Device list to see events tracked in debug_mode.

Making the switch to Google Analytics 4

Google Analytics 4 is fully equipped to support your measurement needs today and into the future. Google will be turning down Universal Analytics, so it is recommended you to make the switch to Google Analytics 4 as soon as possible. To get help in migrating to GA4, you can refer to Google's docs here.

On July 1, 2023, standard Universal Analytics properties will no longer process data. You'll be able to see your Universal Analytics reports for a period of time after July 1, 2023. However, new data will only flow into Google Analytics 4 properties.

Differences Between Native Google Analytics 4 and Freshpaint Google Analytics 4 Proxy

Out of the box there will be some differences between a native Google Analytics 4 integration and a Freshpaint Google Analytics 4 integration. These are currently the following:

• Events sent from Freshpaint to Google Analytics 4 when the destination is in HIPAA mode will only have state-level geolocation information attached to them.

• Enhanced measurement events are not configured out of the box. If you have enhanced event measurement enabled, a native Google Analytics integration will capture a number of events out of the box that Freshpaint does not. This includes events such as scroll events and download_file events. If you are interested in capturing these events, contact [e-mail] for assistance in capturing the properties.
• Demographics data is currently not supported.

• An increase in user engagement events is expected after transitioning to Freshpaint. Freshpaint makes continuous effort to emulate Google Analytics' tracking behavior, but strict parity is not possible due to GA4 being closed source. You can read more about this below.

• Reduced Geo-location accuracy for HIPAA customers only - We will reduce the geo-location accuracy to remain in compliance with HIPAA guidance. Google Analytics uses the IP address to geo-locate the user. Freshpaint will replace the IP address of the customer with another IP address within the same State and Country.

Analytics that look at City-level or at a more granular level will produce inaccurate results within Google Analytics due to the IP address replacement, however this is necessary in order to remain HIPAA compliant.

User Engagement Discrepancies

An increase in user engagement events is expected after transitioning to Freshpaint. Freshpaint makes continuous effort to emulate Google Analytics' tracking behavior, but strict parity is not possible due to GA4 being closed source. One example of a known difference between the implementations is detailed below:

Freshpaint's approach triggers a user_engagement event each time a user switches tabs, potentially resulting in multiple events for a single session. In contrast, GA4 consolidates engagement time into a single event, sending it only when the user navigates away or closes the tab. Both methods measure total engagement time but differ in event frequency.

There are some situations that may increase the magnitude of the discrepancy. Those include:

1. Modifying the default user_engagement event within your Google Analytics 4 account. Since this is the event used to determine engagement and bounce rates, changing how this event is defined will change what is being measured, likely leading to a change despite it being the “same” event.

2. Not uninstalling old Google Analytics 4 installations when installing Freshpaint. If GA4 is installed twice, it will send redundant data that may be interpreted by Google Analytics as additional user engagement.

Unfortunately, we can't provide a specific expectation for discrepancies in engagement time or percentage. Since we don't have full visibility into GA4's measurement model, we're unable to directly compare our approach to theirs.

If you'd like help in examining a user engagement discrepancy, please contact us at [e-mail]

Conversion Event Imports Between Google Analytics and Google Ads

The workflow of importing GA4 events as conversion actions in Google Ads is considered non-compliant, primarily related to the handling of user identifiers like the GCLID (Google Click Identifier).

To remain compliant for both GA4 and Google Ads, Freshpaint recommends:

• Not allowlisting the Google Click Identifier (GCLID) property for your Google Analytics destination.

• Creation of net-new Website Conversion Actions in Google Ads: Instead of passing the GCLID directly to GA4, create specific Website conversion actions. This method generates a "conversion label" which allows Freshpaint to map an event to a specific conversion action in Google Ads.

• Sending Data to Google Ads: When sending data to Google Ads, only the GCLID and the conversion label are sent for attribution, using the Google Ads or Google Ads Conversions API destinations.
• Unlinking your Google Analytics 4 property from your Google Ads account. The process for how these 2 tools are unlinked is documented here, under the "Unlinking Google Ads accounts from Analytics" section of the article.

Configuration Settings

Event Transformations

Set up transformations to modify your data before it's sent to your destination. Read more about transformations here.