Cloud Mode

Detailed technical documentation on sending events to Google Analytics 4 using the RudderStack Cloud mode.

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

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

Track

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

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 parameters are listed in the following table:

Parameters	Mapping value
client_id	context.client_id or messageId
app_instance_id	from externalID ga4AppInstanceId

Refer to the FAQ section for more information on how to obtain the app_instance_id.

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"
  }]
}, {
  client_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"
  }],
});

E-commerce

RudderStack supports e-commerce tracking for Google Analytics 4. You can refer to the RudderStack E-commerce 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 event	Google Analytics 4 event
Products Searched	search
Product List Viewed Product Clicked	view_item_list select_item
Promotion Viewed Promotion Clicked	view_promotion select_promotion
Product Viewed Product Added Product Removed Cart Viewed Product Added to Wishlist	view_item add_to_cart remove_from_cart view_cart add_to_wishlist
Checkout Started	begin_checkout
Order Completed Order Refunded	purchase refund
Product Shared Cart Shared	share
Group	join_group
Payment Info Entered	add_payment_info OR add_shipping_info

The mapping of the Payment Info Entered event to the add_payment_info or add_shipping_info event is determined on the basis of parameters passed to it as explained here.

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

RudderStack event	RudderStack property	Google Analytics 4 property
Products Searched	query	search_term
Product List Viewed Product Clicked	properties.list_id properties.category	item_list_id item_list_name
Promotion Viewed Promotion Clicked	properties.position properties.creative_name properties.creative_slot properties.promotion_id properties.promotion_name	location_id creative_name creative_slot promotion_id promotion_name
Product Viewed Product Added Product Removed Cart Viewed Product Added to Wishlist	properties.total properties.currency	value currency
Checkout Started	properties.total properties.currency properties.coupon	value currency coupon
Order Completed Order Refunded	properties.currency properties.order_id properties.total properties.affiliation properties.coupon properties.shipping properties.tax	currency transaction_id value affiliation coupon shipping tax
Product Shared Cart Shared	properties.share_via properties.content_type properties.item_id	method content_type item_id
Group	groupId properties.groupId properties.group_id	group_id
Payment Info Entered	properties.payment_method properties.coupon properties.value properties.currency	payment_type coupon value currency
Payment Info Entered	properties.shipping_method properties.coupon properties.value properties.currency	shipping_tier coupon value currency

The Payment Info Entered event is mapped on the basis of parameters passed to it:

• If payment_method is passed along with the other fields, it maps to add_payment_info event.

• If shipping_method is passed along with the other fields, it maps to add_shipping_info event.

Most of the above mentioned events include items parameter which accepts an Item array. The below table details out the common mappings for Items array:

RudderStack	Google Analytics 4
properties.products.$.product_id	item_id
properties.products.$.name	item_name
properties.products.$.coupon	coupon
properties.products.$.price	price
properties.products.$.position	index
properties.products.$.category	item_category
properties.products.$.brand	item_brand
properties.products.$.variant	item_variant
properties.products.$.quantity	quantity

The below mentioned e-commerce events include items parameter which accepts an Item array.

RudderStack	Presence of items parameter
Product List Viewed	Required
Product Clicked	Required
Product Viewed	Required
Product Added	Required
Product removed	Required
Cart Viewed	Required
Checkout Started	Required
Payment Info entered	Required
Order Completed	Required
Order Refunded	Optional
Product Added to Wishlist	Required
View Search Results	Optional

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

RudderStack	Google Analytics 4
properties.products.$.affiliation	affiliation
properties.products.$.currency	currency
properties.products.$.discount	discount
properties.products.$.item_category2	item_category2
properties.products.$.item_category3	item_category3
properties.products.$.item_category4	item_category4
properties.products.$.item_category5	item_category5
properties.products.$.item_list_id	item_list_id
properties.products.$.item_list_name	item_list_name
properties.products.$.location_id	location_id

The below mentioned e-commerce events include items parameter which accepts an Item array.

RudderStack	Presence of items parameter
Promotion Viewed	Required
Promotion Clicked	Optional

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

RudderStack	Google Analytics 4
properties.products.$.affiliation	affiliation
properties.products.$.creative_name	creative_name
properties.products.$.creative_slot	creative_slot
properties.products.$.currency	currency
properties.products.$.discount	discount
properties.products.$.item_category2	item_category2
properties.products.$.item_category3	item_category3
properties.products.$.item_category4	item_category4
properties.products.$.item_category5	item_category5
properties.products.$.item_list_id	item_list_id
properties.products.$.item_list_name	item_list_name
properties.products.$.location_id	location_id
properties.products.$.promotion_id	promotion_id
properties.products.$.promotion_name	promotion_name

Non e-commerce events

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 Mapping	Property Mapping
RudderStack	Google Analytics 4	RudderStack	Google Analytics 4
earn_virtual_currency	earn_virtual_currency	properties.virtual_currency_name properties.value	virtual_currency_name value
generate_lead	generate_lead	properties.currency properties.value	currency value
level_up	level_up	properties.level properties.character	level character
login	login	properties.method	method
post_score	post_score	properties.level properties.score properties.character	level properties.score character
select_content	select_content	properties.content_type properties.item_id	content_type item_id
sign_up	sign_up	properties.method	method
spend_virtual_currency	spend_virtual_currency	properties.value properties.virtual_currency_name properties.item_name	value virtual_currency_name properties.item_name
tutorial_begin	tutorial_begin	-	-
tutorial_complete	tutorial_complete	-	-
unlock_achievement	unlock_achievement	properties.achievement_id	achievement_id
view_search_results	view_search_results	properties.search_term	search_term

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.

FAQ

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 document 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 the app_instance_id?

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

• Android: getAppInstanceId()

• Kotlin: getAppInstanceId()

• Swift: appInstanceID()

• Objective-C: appInstanceID

• C++: GetAnalyticsInstanceId()

• Unity: GetAnalyticsInstanceIdAsync()

Contact us

For queries on any of the sections covered in this guide, you can contact us or start a conversation in our Slack community.