RudderStack lets you send your event data to Google Analytics 4 via cloud mode by leveraging the Google Analytics 4 Measurement Protocol.

Note that Google Analytics 4 does not officially support a complete server-to-server integration. RudderStack utilizes the GA4 Measurement Protocol API for our cloud mode integration, which does not currently allow ingestion of UTM parameters for attribution reporting. This may significantly limit your ability to use certain GA4 reporting features. Please refer to Google’s documentation for more information on these limitations.

Github Badge
Find the open source transformer code for this destination in the GitHub repository.

Tagging methods

RudderStack supports both the gtag and firebase ways for tagging in websites in the cloud mode. However, note that:

  • If you use gtag, passing the client_id parameter is mandatory.
  • If you use firebase, passing the app_instance_id parameter is mandatory.
Refer to the Google Analytics 4 Measurement Protocol guide for more information.

The mappings for the above-mentioned mandatory parameters are listed in the following table:

ParametersMapping value
client_idRefer to the Mapping client_id section.
app_instance_idfrom externalID ga4AppInstanceId
Refer to the FAQ section for more information on how to obtain the app_instance_id.

Mapping client_id

RudderStack maps the GA4 client_id in the following order of precedence:

  • If a value is provided in the RudderStack dashboard's GA4 client_id Field Identifier setting, it looks up that value in the event payload and maps it to client_id.
  • If no value is provided in the above dashboard setting or a value is provided in the dashboard but not in the event payload, then RudderStack maps client_id from the following fields in the exact priority order as listed below:
    • From externalID: ga4ClientId
    • From anonymousId
    • From messageId

Supported mappings

The following table lists the mappings for the optional parameters (common for both gtag and firebase):

Optional ParametersMapping valueDescription
user_iduserId/traits.userId/traits.id/context.traits.userId/context.traits.idUnique identifier for a user which helps Google Analytics 4 know if two devices/browsers belong to the same user.
timestamp_microsoriginalTimestamp/timestampTimestamp in ISO 8601 format.
non_personalized_adscontext.device.adTrackingEnabledIndicates whether the events should be used for personalized ads. If context.device.adTrackingEnabled is set as true, non_personalised_ads will be set to false.
Google Analytics 4 Measurement Protocol only supports timestamps 72 hours into the past and 15 minutes into the future. RudderStack discards any event with a timestamp out of this range.

Identify

The identify call lets you identify a user and associate them to their actions. It also lets you record any traits about them like their name, email, etc.

For more information on the dashboard settings related to identify events, refer to the Identify settings section.

A sample identify call using gtag is shown below:

rudderanalytics.identify("1hKOmRA4GRlm", {
firstLogin: true,
method: "Google",
value: 10,
currency: "USD"
});

A sample identify call using firebase is shown below:

rudderanalytics.identify("1hKOmRA4GRlm", {
firstLogin: true,
method: "Google",
value: 10,
currency: "USD"
}, {
externalId: [{
type: "ga4AppInstanceId",
id: "f0dd99b6f979fb551ce583373900f937"
}],
});

Track

The track call lets you capture user events along with the properties associated with them.

A sample track call using gtag is shown below:

rudderanalytics.track('Product List Viewed', {
list_id: "related_products",
category: "Related_products",
products: [{
product_id: "507f1f77bcf86cd799439011",
name: "Monopoly: 3rd Edition",
coupon: "SUMMER_FUN",
category: "Apparel",
brand: "Google",
variant: "green",
price: "19",
quantity: "2",
position: "1",
affiliation: "Google Merchandise Store",
currency: "USD",
discount: 2.22,
item_category2: "Adult",
item_category3: "Shirts",
item_category4: "Crew",
item_category5: "Short sleeve",
item_list_id: "related_products",
item_list_name: "Related Products",
location_id: "L_12345"
}]
}, {
externalId: [{
type: "ga4ClientId",
id: "client_id"
}],
});

A sample track call using firebase is shown below:

rudderanalytics.track('Product List Viewed', {
list_id: "related_products",
category: "Related_products",
products: [{
product_id: "507f1f77bcf86cd799439011",
name: "Monopoly: 3rd Edition",
coupon: "SUMMER_FUN",
category: "Apparel",
brand: "Google",
variant: "green",
price: "19",
quantity: "2",
position: "1",
affiliation: "Google Merchandise Store",
currency: "USD",
discount: 2.22,
item_category2: "Adult",
item_category3: "Shirts",
item_category4: "Crew",
item_category5: "Short sleeve",
item_list_id: "related_products",
item_list_name: "Related Products",
location_id: "L_12345"
}]
}, {
externalId: [{
type: "ga4AppInstanceId",
id: "f0dd99b6f979fb551ce583373900f937"
}],
});

Page

The page call lets you record your website's page views with any additional relevant information about the viewed page.

RudderStack maps the page call to a page_view event by default, and passes it to Google Analytics 4 as a custom event.

As mentioned in the track section above, the RudderStack cloud mode supports both the gtag and firebase methods for tagging in websites.

A sample page call using gtag is shown below:

rudderanalytics.page();

A sample page call using firebase is shown below:

rudderanalytics.page({}, {
externalId: [{
type: "ga4AppInstanceId",
id: "f0dd99b6f979fb551ce583373900f937"
}],
});

Supported mappings

The following table lists the property mappings between RudderStack and Google Analytics 4:

RudderStack propertyGoogle Analytics 4 property
context.page.referrerpage_referrer
context.page.titlepage_title
context.page.urlpage_location

Group

The group call lets you link an identified user with a group such as a company, organization, or an account, and record any traits associated with that group, for example, company name, number of employees, etc.

RudderStack maps the group call to the join_group event by default.

A sample group call using gtag is shown below:

rudderanalytics.group("1hKOmRA4", {
"custom1": 1234,
"custom2": "custom2"
});

A sample group call using firebase is shown below:

rudderanalytics.group("1hKOmRA4", {
"custom1": 1234,
"custom2": "custom2"
}, {
externalId: [{
type: "ga4AppInstanceId",
id: "f0dd99b6f979fb551ce583373900f937"
}],
});

E-commerce event tracking

RudderStack supports e-commerce tracking for Google Analytics 4. You can refer to the E-commerce Events Specification guide for sending events while instrumenting your site with the RudderStack SDK.

The following table lists the mappings between the RudderStack and Google Analytics 4 events:

RudderStack eventGoogle Analytics 4 event
Products Searchedsearch
Product List Viewedview_item_list
Product Clickedselect_item
Promotion Viewedview_promotion
Promotion Clickedselect_promotion
Product Viewedview_item
Product Addedadd_to_cart
Product Removedremove_from_cart
Cart Viewedview_cart
Product Added to Wishlistadd_to_wishlist
Checkout Startedbegin_checkout
Order Completedpurchase
Order Refundedrefund
Product Sharedshare
Cart Sharedshare
Payment Info Enteredadd_payment_info
Checkout Step Completedadd_shipping_info

The following table lists the RudderStack and Google Analytics 4 properties mappings based on the specific RudderStack events:

RudderStack eventRudderStack propertyGoogle Analytics 4 property
Products Searchedproperties.querysearch_term
Product List Viewed
Product Clicked
properties.list_id
properties.category
item_list_id
item_list_name
Promotion Viewed
Promotion Clicked
properties.creative_name
properties.creative
creative_name
properties.creative_slot
properties.position
creative_slot
properties.location_idlocation_id
properties.promotion_name
properties.name
promotion_name
properties.promotion_idpromotion_id
Product Viewed
Product Added to Wishlist
properties.currencycurrency
properties.total
properties.price
properties.value
properties.revenue
value
Product Added
Product Removed
properties.currencycurrency
properties.total
properties.value
properties.revenue
properties.price X properties.quantity
value
Cart Viewedproperties.currencycurrency
properties.total
properties.value
properties.revenue
value
Checkout Startedproperties.currency
properties.coupon
currency
coupon
properties.total
properties.value
properties.revenue
value
Order Completed
Order Refunded
properties.currency
properties.order_id
properties.affiliation
properties.coupon
properties.shipping
properties.tax
currency
transaction_id
affiliation
coupon
shipping
tax
properties.total
properties.value
properties.revenue
value
Product Sharedproperties.share_via
properties.content_type
method
content_type
properties.item_id
properties.product_id
properties.sku
item_id
Cart Sharedproperties.share_via
properties.content_type
method
content_type
properties.item_id
properties.cart_id
item_id
GroupgroupIdgroup_id
Payment Info Enteredproperties.payment_method
properties.coupon
properties.currency
payment_type
coupon
currency
properties.total
properties.value
properties.revenue
value
Checkout Step Completedproperties.currencycurrency
properties.total
properties.value
properties.revenue
value
properties.couponcoupon
properties.shipping_methodshipping_tier

Most of the above mentioned events include the products parameter (mapped to the items parameter) which accepts a products array.

The below table details out the common mappings for the products array:

RudderStackGoogle Analytics 4
properties.products.$.product_iditem_id
properties.products.$.nameitem_name
properties.products.$.couponcoupon
properties.products.$.priceprice
properties.products.$.positionindex
properties.products.$.categoryitem_category
properties.products.$.branditem_brand
properties.products.$.variantitem_variant
properties.products.$.quantityquantity

The below mentioned e-commerce events include the products parameter which accepts a products array.

RudderStackPresence of products parameter
Product List ViewedRequired
Product ClickedRequired
Product ViewedRequired
Product AddedRequired
Product removedRequired
Cart ViewedRequired
Checkout StartedRequired
Payment Info enteredRequired
Order CompletedRequired
Order RefundedOptional
Product Added to WishlistRequired
View Search ResultsOptional

The following table details the parameter mappings present in the products array, for the above events:

RudderStackGoogle Analytics 4
properties.products.$.affiliationaffiliation
properties.products.$.currencycurrency
properties.products.$.discountdiscount
properties.products.$.item_category2item_category2
properties.products.$.item_category3item_category3
properties.products.$.item_category4item_category4
properties.products.$.item_category5item_category5
properties.products.$.item_list_iditem_list_id
properties.products.$.item_list_nameitem_list_name
properties.products.$.location_idlocation_id

The below mentioned e-commerce events include the products parameter (mapped to the items parameter) which accepts a products array.

RudderStackPresence of products parameter
Promotion ViewedRequired
Promotion ClickedOptional

The following table details the parameter mappings present in the products array, for the above events:

RudderStackGoogle Analytics 4
properties.products.$.affiliationaffiliation
properties.products.$.creative_namecreative_name
properties.products.$.creative_slotcreative_slot
properties.products.$.currencycurrency
properties.products.$.discountdiscount
properties.products.$.item_category2item_category2
properties.products.$.item_category3item_category3
properties.products.$.item_category4item_category4
properties.products.$.item_category5item_category5
properties.products.$.item_list_iditem_list_id
properties.products.$.item_list_nameitem_list_name
properties.products.$.location_idlocation_id
properties.products.$.promotion_idpromotion_id
properties.products.$.promotion_namepromotion_name

Non e-commerce events tracking

The below table lists the mappings of the non e-commerce track events and properties that are passed to Google Analytics 4 events and properties:

Event MappingProperty Mapping
RudderStackGoogle Analytics 4RudderStackGoogle Analytics 4
generate_leadgenerate_leadproperties.${currency}
properties.${value}
currency
value
loginloginproperties.${method}method
sign_upsign_upproperties.${method}method
view_search_resultsview_search_resultsproperties.search_termsearch_term
The {currency}, {value}, and {method} properties mentioned above are dynamic and their actual value depends on the key name passed in the dashboard. Refer to the Identify section for more information.
You can pass the custom user properties to any of the events by passing them as properties.user_properties. Refer to the Google Analytics 4 documentation for more information.

Rules for naming custom events

You must follow the below rules while choosing a name for the custom events:

  • Event names are case sensitive. For example, my_event and My_Event are two distinct events.
  • Event names must start with a letter. Only letters, numbers, and underscores are permitted. DO NOT use spaces.
  • Do not use reserved prefixes and event names. Refer to the FAQ section to know more about the reserved event names and prefixes.

Tracking active users and sessions

As Google Analytics 4 only reports the users who engage with your website for a non-zero time, RudderStack sets the engagement_time_msec parameter to 1, by default. To track engagement time in your events, you can set the engagement_time_msec field to a different value.

RudderStack maps the following properties to GA4's engagement_time_msec property:

RudderStack propertiesGoogle Analytics 4 property
traits.engagementTimeMsec
context.traits.engagementTimeMsec
traits.engagement_time_msec
context.traits.engagement_time_msec
engagement_time_msec

You can use the Google Analytics 4 session_id parameter to identify the session associated with a particular event.

To read more about sessions in Google Analytics 4, refer to this Google Analytics 4 Help article.

RudderStack maps the following properties to GA4's session_id property:

RudderStack propertiesGoogle Analytics 4 property
traits.sessionId
context.traits.sessionId
traits.session_id
context.traits.session_id
session_id
RudderStack automatically collects engagement_time_msec and session_id when sending events via the device mode. However, they must be manually passed while sending events via the cloud mode.
For more information on the optional reporting parameters in Google Analytics 4, refer to their documentation.

FAQ

I’ve set up GA4 as a destination in RudderStack but I’m not seeing the expected data flow through in the GA4 dashboard. What should I do?

To view the events sent to GA4, go to your Google Analytics dashboard and navigate to Reports > Realtime.

While the events typically show up within a few seconds, note that it can take GA4 up to 24 hours to process their data and appear on other reports. Also, not all types of data flow through to its realtime dashboard. It may be best to consult GA4’s FAQs for the most up-to-date information on its latest capabilities and limitations.

For more information on checking the realtime view or verifying your implementation, refer to this GA4 documentation. You can also refer to this Troubleshooting guide for steps on fixing any implementation errors.

What are the reserved prefixes in Google Analytics 4?

The reserved prefixes in Google Analytics 4 cannot be used for custom events. The list of such prefixes is mentioned below:

  • _ (underscore)
  • firebase_
  • ga_
  • google_
  • gtag.

Refer to the GA4 documentation for more information.

What are the reserved event, parameter, and user property names in Google Analytics 4?

Google Analytics 4 has some reserved event, parameter, and user property names that cannot be used. Refer to the Measurement Protocol (Google Analytics 4) guide for a complete list of reserved names.

How do I obtain app_instance_id?

You can retrieve app_instance_id through the Firebase SDK depending on the platform where the SDK is installed:

Refer to the GA4 documentation for more information.


Contact us

For more information on the topics covered on this page, email us or start a conversation in our Slack community.