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.

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:

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

externalId

You can use externalID to send a custom client_id that is external to RudderStack.

There are certain scenarios where you may want to send a custom client_id. For example, if you maintain a user with a certain identifier, then you may prefer to pass it as the custom client_id as a part of externalId:

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

This destination does not strictly adhere to the RudderStack Ecommerce Event Spec.

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. However, RudderStack recommends using the page call to record page-related information for your website specifically.

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.

Supported mappings

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.

Custom events

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

Follow the below 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. Only letters, numbers, and underscores are permitted. Do not use spaces.
• Do not use reserved prefixes and event names. The list of such prefixes is mentioned 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:

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

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 or check Debug View (only available in device mode). For more information, see 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. See GA4 documentation for more information on verifying your implementation or checking the realtime view.

You can also see the GA4 Troubleshooting guide for steps on identifying and fixing any possible implementation issues.

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

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 via hybrid mode).

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:

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

See GA4 documentation for more information.

Questions? Contact us by email or on Slack