Google Analytics 4 cloud mode

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

Google Analytics 4 does not officially support a complete server-to-server integration. RudderStack utilizes the GA4 Measurement Protocol API for 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. Refer to the Google’s documentation for more information on these limitations.

For capturing a fuller, more robust set of attribution data while using Measurement Protocol, RudderStack suggests referencing and setting up a hybrid mode connection.

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

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

Mapping client_id

RudderStack maps client_id from the following fields in the same priority order as listed below:

• From externalID: ga4ClientId
• From anonymousId
• From rudderId

Supported mappings

The following table lists the mappings for the gtag and firebase parameters:

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.

Track

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

You can send all the events mentioned in GA4 documentation as track events.

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

Supported mappings

The following table lists the property mappings between RudderStack and Google Analytics 4 for login and sign_up events:

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

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, 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:

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

Ecommerce event tracking

RudderStack supports ecommerce tracking for Google Analytics 4. You can refer to the Ecommerce Events Specification 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:

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

The default unit for currency property is USD.

Out of the above mentioned events, the below ones include the products parameter (mapped to the items parameter) which accepts a products array:

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

The following table lists the property mappings of the products array, specifically for the Promotion Viewed and Promotion Clicked events:

The root-level properties of ecommerce events which do not include a products array are mapped to the following GA4 items array:

Payment Info Entered

The Payment Info Entered event must include the products array apart from the common properties, as shown:

rudderanalytics.track(
  "Payment Info Entered", {
    currency: "USD",
    value: "7.77",
    coupon: "SUMMER_FUN",
    payment_method: "Credit Card",
    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",
    }, ],
  }
);

Promotion Viewed

The Promotion Viewed event must include the products array apart from the common properties, as shown:

rudderanalytics.track(
  "Promotion Viewed", {
    creative: "Summer Banner",
    position: "featured_app_1",
    promotion_id: "P_12345",
    name: "Summer Sale",
    products: [{
      product_id: "507f1f77bcf86cd799439011",
      name: "Monopoly: 3rd Edition",
      coupon: "SUMMER_FUN",
      category: "Apparel",
      brand: "Google",
      variant: "green",
      price: "19",
      quantity: "2",
      position: "0",
      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",
      promotion_id: "P_12345",
      promotion_name: "Summer Sale",
      creative_name: "summer_banner2",
      creative_slot: "featured_app_1",
    }, ],
  }, {
    externalId: [{
      type: "ga4ClientId",
      id: "client_id",
    }, ],
  }
);

Promotion Clicked

The Promotion Clicked event can include the products array optionally, apart from the common properties, as shown:

rudderanalytics.track(
  "Promotion Clicked", {
    creative: "Summer Banner",
    position: "featured_app_1",
    promotion_id: "P_12345",
    name: "Summer Sale",
    products: [{
      product_id: "507f1f77bcf86cd799439011",
      name: "Monopoly: 3rd Edition",
      coupon: "SUMMER_FUN",
      category: "Apparel",
      brand: "Google",
      variant: "green",
      price: "19",
      quantity: "2",
      position: "0",
      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",
      promotion_id: "P_12345",
      promotion_name: "Summer Sale",
      creative_name: "summer_banner2",
      creative_slot: "featured_app_1",
    }, ],
  }, {
    externalId: [{
      type: "ga4ClientId",
      id: "client_id",
    }, ],
  }
);

Checkout Step Completed

The Checkout Step Completed event must include the products array apart from the common properties, as shown:

rudderanalytics.track(
  "Checkout Step Completed", {
    currency: "USD",
    value: "7.77",
    coupon: "SUMMER_FUN",
    shipping_method: "Ground",
    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",
    }, ],
  }
);

Non ecommerce events tracking

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

You can pass the custom user properties to any of the events by passing them as properties.user_properties or context.traits. 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 learn 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:

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 session properties for the group call:

RudderStack maps the following session properties for the track and page calls:

RudderStack automatically collects engagement_time_msec and session_id when sending events via device mode. However, they must be manually passed while sending events via cloud mode.

For more information on the optional reporting parameters in Google Analytics 4, refer to their documentation.

Hybrid mode

Hybrid mode sends your event data to Google Analytics 4 via both the native SDK (device mode) and the Google Analytics 4 Measurement Protocol (cloud mode). See Hybrid mode to learn more.

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:

• Android: getAppInstanceId()
• Kotlin: getAppInstanceId()
• Swift: appInstanceID()
• Objective-C: appInstanceID
• C++: GetAnalyticsInstanceId()
• Unity: GetAnalyticsInstanceIdAsync()

Refer to the GA4 documentation for more information.

Questions? Contact us by email or on Slack