> For the complete documentation index, see [llms.txt](https://rudderlabs.gitbook.io/rudderlabs-1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rudderlabs.gitbook.io/rudderlabs-1/docs/destinations/analytics/google-analytics-4/google-analytics-4-cloud-mode.md).

# 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](https://www.rudderstack.com/docs/rudderstack-cloud/rudderstack-connection-modes/#cloud-mode).

Find the open source transformer code for this destination in the [GitHub repository](https://github.com/rudderlabs/rudder-transformer/tree/master/v0/destinations/ga4).

## Track

The [`track`](https://www.rudderstack.com/docs/rudderstack-api/api-specification/rudderstack-spec/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](https://developers.google.com/analytics/devguides/collection/protocol/ga4/reference?client_type=gtag#payload) 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](#faq) section for more information on how to obtain the `app_instance_id`.

A sample `track` call using `gtag` is shown below:

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

```javascript
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`](https://www.rudderstack.com/docs/rudderstack-api/api-specification/rudderstack-spec/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`](#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:

```javascript
rudderanalytics.page();
```

A sample `page` call using `firebase` is shown below:

```javascript
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](https://rudderstack.com/docs/rudderstack-api/api-specification/rudderstack-ecommerce-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 event                                                                                     | Google Analytics 4 event                                                                                                                                     |
| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Products Searched                                                                                     | `search`                                                                                                                                                     |
| <p>Product List Viewed<br>Product Clicked</p>                                                         | <p><code>view\_item\_list</code><br><code>select\_item</code></p>                                                                                            |
| <p>Promotion Viewed<br>Promotion Clicked</p>                                                          | <p><code>view\_promotion</code><br><code>select\_promotion</code></p>                                                                                        |
| <p>Product Viewed<br>Product Added<br>Product Removed<br>Cart Viewed<br>Product Added to Wishlist</p> | <p><code>view\_item</code><br><code>add\_to\_cart</code><br><code>remove\_from\_cart</code><br><code>view\_cart</code><br><code>add\_to\_wishlist</code></p> |
| Checkout Started                                                                                      | `begin_checkout`                                                                                                                                             |
| <p>Order Completed<br>Order Refunded</p>                                                              | <p><code>purchase</code><br><code>refund</code></p>                                                                                                          |
| <p>Product Shared<br>Cart Shared</p>                                                                  | `share`                                                                                                                                                      |
| Group                                                                                                 | `join_group`                                                                                                                                                 |
| Payment Info Entered                                                                                  | <p><code>add\_payment\_info</code><br>OR<br><code>add\_shipping\_info</code></p>                                                                             |

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](https://www.rudderstack.com/docs/destinations/analytics/google-analytics-4/google-analytics-4-cloud-mode/#:~:text=currency-,The%20Payment%20Info%20Entered%20event%20is%20mapped%20on%20the%20basis,event.,-Most%20of%20the).

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`                                                                                                                                                                      |
| <p>Product List Viewed<br>Product Clicked</p>                                                         | <p><code>properties.list\_id</code><br><code>properties.category</code></p>                                                                                                                                                                               | <p><code>item\_list\_id</code><br><code>item\_list\_name</code></p>                                                                                                                |
| <p>Promotion Viewed<br>Promotion Clicked</p>                                                          | <p><code>properties.position</code><br><code>properties.creative\_name</code><br><code>properties.creative\_slot</code><br><code>properties.promotion\_id</code><br><code>properties.promotion\_name</code></p>                                           | <p><code>location\_id</code><br><code>creative\_name</code><br><code>creative\_slot</code><br><code>promotion\_id</code><br><code>promotion\_name</code></p>                       |
| <p>Product Viewed<br>Product Added<br>Product Removed<br>Cart Viewed<br>Product Added to Wishlist</p> | <p><code>properties.total</code><br><code>properties.currency</code></p>                                                                                                                                                                                  | <p><code>value</code><br><code>currency</code></p>                                                                                                                                 |
| Checkout Started                                                                                      | <p><code>properties.total</code><br><code>properties.currency</code><br><code>properties.coupon</code></p>                                                                                                                                                | <p><code>value</code><br><code>currency</code><br><code>coupon</code></p>                                                                                                          |
| <p>Order Completed<br>Order Refunded</p>                                                              | <p><code>properties.currency</code><br><code>properties.order\_id</code><br><code>properties.total</code><br><code>properties.affiliation</code><br><code>properties.coupon</code><br><code>properties.shipping</code><br><code>properties.tax</code></p> | <p><code>currency</code><br><code>transaction\_id</code><br><code>value</code><br><code>affiliation</code><br><code>coupon</code><br><code>shipping</code><br><code>tax</code></p> |
| <p>Product Shared<br>Cart Shared</p>                                                                  | <p><code>properties.share\_via</code><br><code>properties.content\_type</code><br><code>properties.item\_id</code></p>                                                                                                                                    | <p><code>method</code><br><code>content\_type</code><br><code>item\_id</code></p>                                                                                                  |
| Group                                                                                                 | <p><code>groupId</code><br><code>properties.groupId</code><br><code>properties.group\_id</code></p>                                                                                                                                                       | `group_id`                                                                                                                                                                         |
| Payment Info Entered                                                                                  | <p><code>properties.payment\_method</code><br><code>properties.coupon</code><br><code>properties.value</code><br><code>properties.currency</code></p>                                                                                                     | <p><code>payment\_type</code><br><code>coupon</code><br><code>value</code><br><code>currency</code></p>                                                                            |
| Payment Info Entered                                                                                  | <p><code>properties.shipping\_method</code><br><code>properties.coupon</code><br><code>properties.value</code><br><code>properties.currency</code></p>                                                                                                    | <p><code>shipping\_tier</code><br><code>coupon</code><br><code>value</code><br><code>currency</code></p>                                                                           |

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`](https://developers.google.com/analytics/devguides/collection/protocol/ga4/reference/events#view_item_list) 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`](https://developers.google.com/analytics/devguides/collection/protocol/ga4/reference/events#view_item_list) 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`](https://developers.google.com/analytics/devguides/collection/protocol/ga4/reference/events#view_item_list) 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`  | <p><code>properties.virtual\_currency\_name</code><br><code>properties.value</code></p>                                       | <p><code>virtual\_currency\_name</code><br><code>value</code></p>                                       |
| generate\_lead           | `generate_lead`          | <p><code>properties.currency</code><br><code>properties.value</code></p>                                                      | <p><code>currency</code><br><code>value</code></p>                                                      |
| level\_up                | `level_up`               | <p><code>properties.level</code><br><code>properties.character</code></p>                                                     | <p><code>level</code><br><code>character</code></p>                                                     |
| login                    | `login`                  | `properties.method`                                                                                                           | `method`                                                                                                |
| post\_score              | `post_score`             | <p><code>properties.level</code><br><code>properties.score</code><br><code>properties.character</code></p>                    | <p><code>level</code><br><code>properties.score</code><br><code>character</code></p>                    |
| select\_content          | `select_content`         | <p><code>properties.content\_type</code><br><code>properties.item\_id</code></p>                                              | <p><code>content\_type</code><br><code>item\_id</code></p>                                              |
| sign\_up                 | `sign_up`                | `properties.method`                                                                                                           | `method`                                                                                                |
| spend\_virtual\_currency | `spend_virtual_currency` | <p><code>properties.value</code><br><code>properties.virtual\_currency\_name</code><br><code>properties.item\_name</code></p> | <p><code>value</code><br><code>virtual\_currency\_name</code><br><code>properties.item\_name</code></p> |
| 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](https://developers.google.com/analytics/devguides/collection/protocol/ga4/user-properties?client_type=gtag) 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](#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](https://support.google.com/analytics/answer/10085872#zippy=%2Cweb%2Cin-this-article%2Creserved-prefixes-and-event-names) 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)](https://developers.google.com/analytics/devguides/collection/protocol/ga4/reference?client_type=gtag#reserved_names) 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()`](https://firebase.google.com/docs/reference/android/com/google/firebase/analytics/FirebaseAnalytics#public-taskstring-getappinstanceid)
* [Kotlin: `getAppInstanceId()`](https://firebase.google.com/docs/reference/kotlin/com/google/firebase/analytics/FirebaseAnalytics#getappinstanceid)
* [Swift: `appInstanceID()`](https://firebase.google.com/docs/reference/swift/firebaseanalytics/api/reference/Classes/Analytics#appinstanceid)
* [Objective-C: `appInstanceID`](https://firebase.google.com/docs/reference/ios/firebaseanalytics/api/reference/Classes/FIRAnalytics#+appinstanceid)
* [C++: `GetAnalyticsInstanceId()`](https://firebase.google.com/docs/reference/cpp/namespace/firebase/analytics#getanalyticsinstanceid)
* [Unity: `GetAnalyticsInstanceIdAsync()`](https://firebase.google.com/docs/reference/unity/class/firebase/analytics/firebase-analytics#getanalyticsinstanceidasync)

## Contact us

For queries on any of the sections covered in this guide, you can [contact us](mailto:%20docs@rudderstack.com) or start a conversation in our [Slack](https://rudderstack.com/join-rudderstack-slack-community) community.