> For the complete documentation index, see [llms.txt](https://docs.chord.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chord.co/activate/event-streaming/destinations/analytics/google-analytics-4/ga4-browser.md).

# GA4 browser

Google Analytics 4 (GA4) is a web and app analytics tool that tracks user behavior across digital properties. This destination loads Google's tag in the shopper's browser. For server-side events, see the [GA4 Measurement Protocol](/activate/event-streaming/destinations/analytics/google-analytics-4/ga4-measurement-protocol.md) version, and [Google Analytics 4](/activate/event-streaming/destinations/analytics/google-analytics-4.md) for how the two fit together.

## Getting started

You need the Measurement ID from your Google Analytics property. To find it, see [Google's support documentation](https://support.google.com/analytics/answer/9539598?hl=en).

## Settings

* **Destination Name** (required): a name to tell this destination apart.
* **Measurement ID** (required): the Measurement ID of your Google Analytics 4 property.
* **Auto Page View** (optional): rely on Google's [enhanced event measurement](https://support.google.com/analytics/answer/9216061#page_view) to track page views. When it is on, Chord ignores the `page` event. On by default.
* **Forward Extra Event Properties** (optional): send event properties that the built-in GA4 mapping does not cover to GA4 automatically. Mapped properties always take precedence. Off by default.
* **Custom Events and Parameters** (optional): map custom Chord events to GA4 events and set their parameters. Each entry has a **Chord Event Name to Map**, a **Google Event Name to Map** and a list of **Parameters**. Each parameter pairs an **Event Property** with a **Google Property**.
* **Ad Consent Category** (optional): the consent category from your consent tool that controls advertising consent. When set, Chord forwards the choice to Google as the `ad_storage`, `ad_user_data` and `ad_personalization` signals (Consent Mode v2). Select "None" to turn off Consent Mode v2 for this destination.
* **Analytics Consent Category** (optional): the consent category from your consent tool that controls analytics consent. When set, Chord forwards the choice to Google as the `analytics_storage` signal (Consent Mode v2). Select "None" to leave the analytics storage signal out.
* **Consent Requirements** (optional): the consent categories a visitor must accept before Chord sends data to this destination. See [Consent](/activate/event-streaming/consent.md).

## Connect

Add **Google Analytics 4 (Device Mode)** from the destination catalog, using the settings above. See [Connect a destination](/activate/event-streaming/connect-a-destination.md) for the full steps.

## Event mapping

Not all Chord tracking events are used downstream in your configured destinations. The most relevant events in the Chord tracking plan are mapped within the destination, relayed and then ingested in GA4.

| Chord event                                                                           | GA4 event                                        | Notes |
| ------------------------------------------------------------------------------------- | ------------------------------------------------ | ----- |
| [Cart Viewed](/collect-data/tracking-plan/cart-viewed.md)                             | `view_cart`                                      |       |
| [Checkout Started](/collect-data/tracking-plan/checkout-started.md)                   | `begin_checkout`                                 |       |
| Generate Lead                                                                         | `generate_lead`                                  |       |
| [Order Completed](/collect-data/tracking-plan/order-completed.md)                     | `purchase`                                       |       |
| [Order Refunded](/collect-data/tracking-plan/order-refunded.md)                       | `refund`                                         |       |
| Page                                                                                  | `page_view`, only when **Auto Page View** is off |       |
| [Payment Info Entered](/collect-data/tracking-plan/payment-info-entered.md)           | `add_payment_info`                               |       |
| [Product Added](/collect-data/tracking-plan/product-added.md)                         | `add_to_cart`                                    |       |
| [Product Added to Wishlist](/collect-data/tracking-plan/product-added-to-wishlist.md) | `add_to_wishlist`                                |       |
| [Product Clicked](/collect-data/tracking-plan/product-clicked.md)                     | `select_item`                                    |       |
| [Product List Viewed](/collect-data/tracking-plan/product-list-viewed.md)             | `view_item_list`                                 |       |
| [Product Removed](/collect-data/tracking-plan/product-removed.md)                     | `remove_from_cart`                               |       |
| [Product Viewed](/collect-data/tracking-plan/product-viewed.md)                       | `view_item`                                      |       |
| [Products Searched](/collect-data/tracking-plan/products-searched.md)                 | `search`                                         |       |
| [Promotion Clicked](/collect-data/tracking-plan/promotion-clicked.md)                 | `select_promotion`                               |       |
| [Promotion Viewed](/collect-data/tracking-plan/promotion-viewed.md)                   | `view_promotion`                                 |       |
| [Signed In](/collect-data/tracking-plan/signed-in.md)                                 | `login`                                          |       |
| [Signed Up](/collect-data/tracking-plan/signed-up.md)                                 | `sign_up`                                        |       |

Any other event is sent under its own name. See [Custom events](#custom-events).

## Event value

Wherever a table below says "event value", Chord uses the first of these that is present:

1. `properties.value`
2. `properties.total`
3. `properties.price`
4. The sum of each product's `price` times `quantity`
5. `properties.revenue`

## Order Completed (`purchase`)

| Chord source (priority order)                                               | GA4 field        | Notes                                                                            |
| --------------------------------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------- |
| `properties.order_id` > `properties.orderId` > `properties.id`              | `transaction_id` | Order identifier. A cart ID is never used here                                   |
| Event value                                                                 | `value`          | Conversion value                                                                 |
| `properties.currency` > `properties.meta.i18n.currency` > `"USD"` (default) | `currency`       |                                                                                  |
| `properties.coupon`                                                         | `coupon`         | Coupon code; omitted if not present                                              |
| `properties.shipping`                                                       | `shipping`       | Shipping cost; omitted if not present                                            |
| `properties.tax`                                                            | `tax`            | Tax amount; omitted if not present                                               |
| `properties.discount`                                                       | `discount`       | Discount amount; omitted if not present                                          |
| `properties.affiliation`                                                    | `affiliation`    | Store affiliation; omitted if not present                                        |
| `properties.products[]`                                                     | `items`          | Array of product items (see [Product item attributes](#product-item-attributes)) |

## Product Added (`add_to_cart`)

| Chord source (priority order)                                               | GA4 field  | Notes                                                   |
| --------------------------------------------------------------------------- | ---------- | ------------------------------------------------------- |
| Event value                                                                 | `value`    | Conversion value                                        |
| `properties.currency` > `properties.meta.i18n.currency` > `"USD"` (default) | `currency` |                                                         |
| `properties.discount`                                                       | `discount` | Discount amount; omitted if not present                 |
| The product on the event, or `properties.products[]`                        | `items`    | See [Product item attributes](#product-item-attributes) |

## Checkout Started (`begin_checkout`)

| Chord source (priority order)                                               | GA4 field  | Notes                                                   |
| --------------------------------------------------------------------------- | ---------- | ------------------------------------------------------- |
| Event value                                                                 | `value`    | Conversion value                                        |
| `properties.currency` > `properties.meta.i18n.currency` > `"USD"` (default) | `currency` |                                                         |
| `properties.coupon`                                                         | `coupon`   | Coupon code; omitted if not present                     |
| `properties.products[]`                                                     | `items`    | See [Product item attributes](#product-item-attributes) |

## Order Refunded (`refund`)

| Chord source (priority order)                                               | GA4 field        | Notes                                          |
| --------------------------------------------------------------------------- | ---------------- | ---------------------------------------------- |
| `properties.order_id` > `properties.orderId` > `properties.id`              | `transaction_id` | Order identifier. A cart ID is never used here |
| Event value                                                                 | `value`          | Refund value                                   |
| `properties.currency` > `properties.meta.i18n.currency` > `"USD"` (default) | `currency`       |                                                |
| `properties.coupon`                                                         | `coupon`         |                                                |
| `properties.shipping`                                                       | `shipping`       |                                                |
| `properties.tax`                                                            | `tax`            |                                                |
| `properties.affiliation`                                                    | `affiliation`    |                                                |
| `properties.products[]`                                                     | `items`          |                                                |

## Product Viewed (`view_item`), Cart Viewed (`view_cart`), Product Removed (`remove_from_cart`) and Product Added to Wishlist (`add_to_wishlist`)

| Chord source (priority order)                                               | GA4 field  | Notes |
| --------------------------------------------------------------------------- | ---------- | ----- |
| Event value                                                                 | `value`    |       |
| `properties.currency` > `properties.meta.i18n.currency` > `"USD"` (default) | `currency` |       |
| The product on the event, or `properties.products[]` for Cart Viewed        | `items`    |       |

## Payment Info Entered (`add_payment_info`)

| Chord source (priority order)                                               | GA4 field      | Notes |
| --------------------------------------------------------------------------- | -------------- | ----- |
| Event value                                                                 | `value`        |       |
| `properties.currency` > `properties.meta.i18n.currency` > `"USD"` (default) | `currency`     |       |
| `properties.coupon`                                                         | `coupon`       |       |
| `properties.payment_method`                                                 | `payment_type` |       |
| `properties.products[]`                                                     | `items`        |       |

## Product List Viewed (`view_item_list`) and Product Clicked (`select_item`)

| Chord source (priority order)                                                            | GA4 field        | Notes |
| ---------------------------------------------------------------------------------------- | ---------------- | ----- |
| `properties.list_id`                                                                     | `item_list_id`   |       |
| `properties.category`                                                                    | `item_list_name` |       |
| `properties.products[]` for Product List Viewed, the clicked product for Product Clicked | `items`          |       |

## Promotion Clicked (`select_promotion`) and Promotion Viewed (`view_promotion`)

| Chord source (priority order)                   | GA4 field        | Notes |
| ----------------------------------------------- | ---------------- | ----- |
| `properties.creative_name`                      | `creative_name`  |       |
| `properties.creative`                           | `creative_slot`  |       |
| `properties.position`                           | `location_id`    |       |
| `properties.promotion_id`                       | `promotion_id`   |       |
| `properties.promotion_name` > `properties.name` | `promotion_name` |       |
| The product on the event, if there is one       | `items`          |       |

## Products Searched (`search`)

| Chord source (priority order) | GA4 field     | Notes |
| ----------------------------- | ------------- | ----- |
| `properties.query`            | `search_term` |       |

## Signed In (`login`) and Signed Up (`sign_up`)

| Chord source (priority order)           | GA4 field | Notes |
| --------------------------------------- | --------- | ----- |
| `properties.type` > `properties.method` | `method`  |       |

## Generate Lead (`generate_lead`)

| Chord source (priority order)                                               | GA4 field  | Notes                                                                                                                                     |
| --------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Event value                                                                 | `value`    |                                                                                                                                           |
| `properties.currency` > `properties.meta.i18n.currency` > `"USD"` (default) | `currency` |                                                                                                                                           |
| The event's other properties                                                | `params`   | Sent together as a single `params` parameter, without `title`, `url`, `path`, `hash`, `search`, `width`, `height`, `value` and `currency` |

## Page (`page_view`)

Chord sends `page_view` only when **Auto Page View** is off. When it is on, Google's own enhanced measurement reports page views and Chord ignores `page` events.

| Chord source (priority order)                                            | GA4 field       | Notes |
| ------------------------------------------------------------------------ | --------------- | ----- |
| `context.page.url` > `properties.url` > the browser's current URL        | `page_location` |       |
| `context.page.title` > `properties.title` > the browser's document title | `page_title`    |       |
| `context.page.path`                                                      | `page_path`     |       |
| `properties.hash`                                                        | `page_hash`     |       |
| `context.page.search`                                                    | `page_search`   |       |
| `context.page.referrer` > `properties.referrer` > the browser's referrer | `page_referrer` |       |

An entry in **Custom Events and Parameters** whose **Chord Event Name to Map** is `page` renames this event and adds its parameters.

## Product item attributes

Each item in the `items` array contains:

| Chord source (priority order)                                 | GA4 field                                                                                                                                                 | Notes                                        |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| product `product_id` > `productId` > `id` > `sku` > `variant` | `item_id`                                                                                                                                                 | Required. A product with no ID is left out   |
| product `name` > `productName` > `product_name`               | `item_name`                                                                                                                                               | Required. A product with no name is left out |
| product `brand`                                               | `item_brand`                                                                                                                                              |                                              |
| product `category` > `productCategory` > `product_category`   | `item_category`                                                                                                                                           |                                              |
| product `variant`                                             | `item_variant`                                                                                                                                            |                                              |
| product `price` > `productPrice`                              | `price`                                                                                                                                                   |                                              |
| product `quantity` > `productQuantity`                        | `quantity`                                                                                                                                                | Defaults to 1                                |
| product `coupon`                                              | `coupon`                                                                                                                                                  |                                              |
| product `discount`                                            | `discount`                                                                                                                                                |                                              |
| product `affiliation`                                         | `affiliation`                                                                                                                                             |                                              |
| product `position`                                            | `index`                                                                                                                                                   |                                              |
| Order `currency`                                              | `currency`                                                                                                                                                | Set on each item                             |
| The product property of the same name                         | `item_category2` to `item_category5`, `item_list_id`, `item_list_name`, `location_id`, `promotion_id`, `promotion_name`, `creative_name`, `creative_slot` |                                              |

## Custom events

Any event that isn't in the table above is sent to GA4 in one of two ways:

* **Listed in Custom Events and Parameters.** Chord sends the **Google Event Name to Map** instead, with the parameters you set. Each **Parameters** row adds one parameter, taken from the **Event Property**. If several entries match the same event, Chord sends one GA4 event for each.
* **Not listed.** Chord sends the event under its own name, in lowercase, with every character other than a letter, number or underscore replaced by `_`, cut to 40 characters. For example, Subscription Created is sent as `subscription_created`. The event's properties are sent as parameters, without `title`, `url`, `path`, `hash`, `search`, `width` and `height`. Chord also sends `currency` and `value`, using the same rules as above.

The same entries also work on the events in the table above. They rename the event, and their parameters are added after Chord's own, so they can replace any of them. Properties not covered by the mapping are sent only when **Forward Extra Event Properties** is on.

## User data

When an event has a User ID, Chord sets it as the GA4 `user_id`. Chord does not send identify events to GA4.

Chord also adds `user_id`, `userId` (when the event has a User ID) and `anonymousId` (when it has one) as parameters on every event.

Traits in `context.traits` are attached to each track event as `{ value }` objects named by trait. Reserved properties (`first_open_time`, `first_visit_time`, `last_deep_link_referrer`, `user_id`, `first_open_after_install`) and properties prefixed with `google_`, `ga_` or `firebase_` are excluded.

## Property mappings

[Property mappings](/activate/event-streaming/property-mappings.md) on the connection are sent as GA4 event parameters on every event, including `page_view` when **Auto Page View** is off. For example, a mapping with **Source** `properties.customer_type` and **Destination** `customer_type` adds a `customer_type` parameter.

A mapping can't set `value`, `currency`, `items` or `transaction_id` on any event, and it doesn't replace a parameter Chord already sets for that event. Personal data such as `email`, `phone` and names is never forwarded.

A mapping sends only the parameter it names. To send every event property to GA4, turn on **Forward Extra Event Properties**.

## CSP requirements

If your site uses a Content Security Policy, allow the following domains:

| Directive     | Domain                                                                 |
| ------------- | ---------------------------------------------------------------------- |
| `script-src`  | `https://www.googletagmanager.com`                                     |
| `connect-src` | `https://www.googletagmanager.com`, `https://www.google-analytics.com` |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.chord.co/activate/event-streaming/destinations/analytics/google-analytics-4/ga4-browser.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.