Google Analytics 4 Cloud Mode Integration

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 sending events in cloud mode, which does not allow ingestion of UTM parameters for attribution reporting currently. This may significantly limit your ability to use certain GA4 reporting features. See the Google Analytics documentation for more information on these limitations.

For capturing a more robust set of attribution data while using Measurement Protocol, RudderStack recommends 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.

See the Google Analytics 4 Measurement Protocol guide for more information.

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

Mapping client_id

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

• From externalID: ga4ClientId
• From anonymousId
• From rudderId

externalId

You can use the externalId object to send a custom GA4 client_id, as shown:

rudderanalytics.identify(
  "1hKOmRA4GRlm", {
    firstName: "Alex",
    city: "New Orleans",
    country: "Louisiana",
    phone: "+1-202-555-0146",
    email: "alex@example.com",
  } {
    externalId: [{
      id: "4718026.1683606287",
      type: "ga4ClientId",
    }, ],
  }
);

Supported mappings

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

Google Analytics 4 Measurement Protocol supports timestamps 72 hours into the past and 15 minutes into the future. RudderStack discards any event with a timestamp that is out of this range.

Track

The track call lets you capture user events along with the properties associated with them. You can use a track call to send any event to Google Analytics 4.

Use the page event to record specific page-related information for your website.

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

A sample track call using gtag is shown:

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

Default mappings

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

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

Page

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

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

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. See the Ecommerce Events Specification for sending events while instrumenting your website with the RudderStack SDK.

Default mappings

You can use the Custom Mappings feature to change these mappings as per your requirement.

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:

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 event 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. See the Google Analytics 4 documentation for more information.

Custom events

You can use custom events to collect additional information that Google Analytics 4 does not collect automatically.

Make sure to follow these rules while choosing a name for the custom events and parameters:

• Event names are case-sensitive. For example, my_event and My_Event are two distinct events.

• Event names must start with a letter. GA4 permits only letters, numbers, and underscores. Do not use spaces.

• Do not use reserved prefixes and event names. The list of these prefixes is listed below:

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

• Do not use spaces in event parameter names.

Custom dimensions and metrics

Before sending events to Google Analytics 4, you must create custom dimensions and metrics in your GA4 dashboard and link them to the event properties/parameters.

You can select a parameter from the list of already collected properties or specify the parameter you plan to collect in the future. RudderStack supports sending user properties via properties.user_properties and context.traits.

Note that:

• Custom dimensions can be either event-scoped or user-scoped. However, custom metrics must be event-scoped.
• Each user property should either be of a number, string, or Boolean data type. This is because GA4 accepts only flat key-value pairs as user properties.
• RudderStack drops any user property that is either an object or an array.

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

You can use the Google Analytics 4 session_id parameter to identify the session associated with a particular event. To know more about sessions in Google Analytics 4, see the Google Analytics 4 help article.

RudderStack maps the following session properties for the group call, by default:

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

Note that:

• Make sure to include the engagement_time_msec and session_id fields while sending events to GA4 in cloud mode.
• Server-side session tracking supports only a subset of user dimensions. Google’s Measurement Protocol API does not support the reserved fields like location, demographics, predefined user dimensions, and device-specific information.

See Google Analytics 4 documentation for more information on the optional reporting parameters.

View events in GA4

To verify if your events are sent to GA4 successfully, go to Reports > Realtime in your Google Analytics dashboard. See the GA4 documentation for more information.

It can take up to 24 hours for the data to be processed in GA4 and appear in the other reports.

Events not showing in GA4

If your events do not show up in GA4’s Realtime view, there could be issues with your implementation.

Not all types of data flow through to GA4’s Realtime dashboard. For example, the Measurement Protocol does not support geolocation data and it does not show up in the Realtime dashboard (except for page calls sent in hybrid mode).

Make sure you are not using a reserved name for your events. This is a common reason for events not showing up in GA4. See FAQ for more information on reserved event names.

Refer to the following resources for verifying your implementation and fixing any possible issues:

• GA4 documentation
• GA4 Troubleshooting guide

FAQ

What does the (not set) value mean in reports?

If you see (not set) value in your reports, see GA4 documentation to diagnose the cause first.

RudderStack utilizes the GA4 Measurement Protocol API for cloud mode integration. It does not support ingestion of UTM parameters for attribution reporting currently.

Some other probable reasons could be:

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. If passed, they are dropped silently. See Measurement Protocol (Google Analytics 4) for a complete list of reserved names. Also, note that Google does not accept any event/user property names that include spaces or fields that include null values.

DebugView

DebugView is only supported in the device mode and is enabled automatically when you set up a device mode GA4 connection. For cloud mode connections, RudderStack sends the events to the validation server and they do not show up in reports.

Validating events

The Google Analytics Measurement Protocol for Google Analytics 4 does not return HTTP error codes, even if an event is malformed or missing required parameters. To ensure your events are valid, you should test them against the Measurement Protocol Validation Server before deploying them to production. See Validating events for more information.

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:

See the GA4 documentation for more information.

Questions? Contact us by email or on Slack