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
Supports HIPAA mode
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.

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

Connection Modes:

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.

Scroll

Freshpaint will automatically scroll events to GA4.

Conversions

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

Using an existing event, or after creating a new event, you must mark that event as a conversion in GA4's dashboard.
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:

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 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.

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 support@freshpaint.io for assistance in capturing the properties.
Demographics data is currently not supported.
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.

Configuration Settings

Event Transformations

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

PreviousGoogle Analytics 4 Proxy Quick Start Guide NextGoogle Analytics 4 Server-Side

Last updated 24 days ago