> 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-measurement-protocol.md).

# GA4 Measurement Protocol

This destination sends event data from Chord to Google Analytics 4 (GA4) server-to-server, using Google's [Measurement Protocol](https://developers.google.com/analytics/devguides/collection/protocol/ga4). It is the server counterpart of the [GA4 browser](/activate/event-streaming/destinations/analytics/google-analytics-4/ga4-browser.md) version, and is typically connected to a back-end site to forward server-side events such as orders and subscriptions. See [Google Analytics 4](/activate/event-streaming/destinations/analytics/google-analytics-4.md) for how the two fit together.

## Getting started

In Google Analytics, create a Measurement Protocol API secret under **Admin > Data Streams > choose your stream > Measurement Protocol API secrets > Create**. Note the stream's measurement ID too. It is under **Admin > Data Streams > choose your stream** and starts with `G-`. For mobile app streams, use the Firebase App ID instead, found in the Firebase console under **Project Settings > General > Your Apps > App ID**.

## Settings

* **Destination Name** (required): a name to tell this destination apart.
* **API Secret** (required): an API secret generated in Google Analytics under **Admin > Data Streams > choose your stream > Measurement Protocol API Secrets > Create**.
* **Measurement ID** (required): the measurement ID of your stream. For web, find it under **Admin > Data Streams > choose your stream > Measurement ID**. For apps, use the Firebase App ID, found in the Firebase console under **Project Settings > General > Your Apps > App ID**.
* **Firebase App ID** (optional): the Firebase App ID of your Firebase app, found in the Firebase console under **Project Settings > General > Your Apps > App ID**. Required for mobile app streams.
* **Measurement Protocol URL** (optional): the endpoint Chord sends to. Defaults to `https://www.google-analytics.com/mp/collect`. The debug URL is `https://www.google-analytics.com/debug/mp/collect`.
* **Events** (optional): which events reach GA4. See [Events setting](#events-setting).
* **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.
* **Use User ID as Client ID Fallback** (optional): when an event has no GA4 client ID or anonymous ID, which is typical for server-side events, send its User ID as the client ID instead of skipping the event. GA4 will not attribute these events to the user's web session. On by default.
* **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 (Measurement Protocol)** from the destination catalog, using the settings above. See [Connect a destination](/activate/event-streaming/connect-a-destination.md) for the full steps.

## Client ID

GA4 requires a `client_id` on every web-stream event. **An event without one is not sent.**

**How the client ID is chosen**

The destination uses the first value it finds, in this order:

1. `context.clientIds.ga4.clientId`: the GA4 client ID from the browser's `_ga` cookie. The Chord analytics SDK captures this automatically on front-end events.
2. The GA4 client ID passed in the event's `integrations` object.
3. The event's `anonymousId`.
4. The event's `userId` (the default fallback, described below).

Front-end events almost always carry the first value, so they need no configuration.

**Default: User ID fallback**

Server-side events, such as orders and subscriptions from your order management system, usually have no browser identifier, so items 1 to 3 are missing. By default, the destination then sends the event's **User ID** as the `client_id` rather than dropping the event.

Keep in mind:

* GA4 treats these events as coming from a different user than that person's web sessions. They will not be attributed to the session, campaign or traffic source that led to the purchase.
* Events with no User ID either are still skipped. The connection's logs show `no client_id found` for each one.
* The fallback does not apply to Firebase app streams, which use the Firebase app instance ID.

**Changing the client ID**

To send a different identifier, add a [property mapping](/activate/event-streaming/property-mappings.md) on the connection with **Destination** set to `context.clientIds.ga4.clientId` and **Source** set to the property you want, for example a GA client ID your server stores. Scope it to the events it applies to. A mapped value takes precedence over every fallback above.

To turn off the User ID fallback, so events without a browser identifier are skipped instead, open the destination and switch off **Use User ID as Client ID Fallback**.

## Events setting

The **Events** field controls which events reach GA4:

* **Empty** (default): sends all track and identify events, and skips page events.
* `*`: sends everything, including page events.
* **A comma-separated list**: sends only the listed event names or types, for example `Order Completed, Subscription Created`.

An event that is not in the list is skipped, and the connection's logs record it as not listed in the destination's Events setting. If an event you expect is missing in GA4, check this field first.

## Event mapping

These Chord events map to GA4 recommended events:

| Chord event                                                                           | GA4 event          | Notes |
| ------------------------------------------------------------------------------------- | ------------------ | ----- |
| Page                                                                                  | `page_view`        |       |
| [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`           |       |
| [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`          |       |

Every event also carries `engagement_time_msec` (default `1`) and, when the event has one, the GA4 `session_id` for your stream.

## Order Completed (`purchase`) and Order Refunded (`refund`)

| Chord source (priority order)                                  | GA4 field        | Notes                                                   |
| -------------------------------------------------------------- | ---------------- | ------------------------------------------------------- |
| `properties.order_id`                                          | `transaction_id` |                                                         |
| `properties.total` > `properties.value` > `properties.revenue` | `value`          |                                                         |
| `properties.currency`                                          | `currency`       | No default. Omitted if not present                      |
| `properties.coupon`                                            | `coupon`         |                                                         |
| `properties.shipping`                                          | `shipping`       |                                                         |
| `properties.tax`                                               | `tax`            |                                                         |
| `properties.affiliation`                                       | `affiliation`    |                                                         |
| `properties.products[]`                                        | `items`          | See [Product item attributes](#product-item-attributes) |

## Other ecommerce events

For these events, `value` is `properties.value` > `properties.total` > `properties.revenue`, and `currency` is `properties.currency`.

| Chord event                                                                            | GA4 event                                                                                                                                                                                                                                             | Notes |
| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| Product Added, Product Viewed, Cart Viewed, Product Removed, Product Added to Wishlist | `value`, `currency`, `items`                                                                                                                                                                                                                          |       |
| Checkout Started                                                                       | `value`, `currency`, `coupon` (`properties.coupon`), `items`                                                                                                                                                                                          |       |
| Payment Info Entered                                                                   | `value`, `currency`, `coupon` (`properties.coupon`), `payment_type` (`properties.payment_method`), `items`                                                                                                                                            |       |
| Product List Viewed, Product Clicked                                                   | `item_list_id` (`properties.list_id`), `item_list_name` (`properties.category`), `items`                                                                                                                                                              |       |
| Promotion Clicked, Promotion Viewed                                                    | `creative_name` (`properties.creative_name`), `creative_slot` (`properties.creative`), `location_id` (`properties.position`), `promotion_id` (`properties.promotion_id`), `promotion_name` (`properties.promotion_name` > `properties.name`), `items` |       |
| Products Searched                                                                      | `search_term` (`properties.query`)                                                                                                                                                                                                                    |       |
| Signed In, Signed Up                                                                   | `method` (`properties.type` > `properties.method`)                                                                                                                                                                                                    |       |
| Generate Lead                                                                          | The event's other properties, without `title`, `url`, `path`, `hash`, `search`, `width`, `height`, `value` and `currency`                                                                                                                             |       |

## Page (`page_view`)

| Chord source (priority order)                   | GA4 field       | Notes                       |
| ----------------------------------------------- | --------------- | --------------------------- |
| `properties.url` > `context.page.url`           | `page_location` | Empty if neither is present |
| `properties.title` > `context.page.title`       | `page_title`    | Empty if neither is present |
| `properties.referrer` > `context.page.referrer` | `page_referrer` | Empty if neither is present |

Page events reach GA4 only when the **Events** setting includes them. See [Events setting](#events-setting).

## Product item attributes

Each item in the `items` array comes from `properties.products[]`. When an event has no `products` array, Chord builds a single item from the event's own properties.

| Chord source (priority order)         | GA4 field                                                                         | Notes                                                |
| ------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------- |
| product `product_id`                  | `item_id`                                                                         | Required. A product with no `product_id` is left out |
| product `name`                        | `item_name`                                                                       | Required. A product with no name is left out         |
| product `brand`                       | `item_brand`                                                                      |                                                      |
| product `category`                    | `item_category`                                                                   |                                                      |
| product `category2` to `category5`    | `item_category2` to `item_category5`                                              |                                                      |
| product `variant`                     | `item_variant`                                                                    |                                                      |
| product `list_id`                     | `item_list_id`                                                                    |                                                      |
| product `list_name`                   | `item_list_name`                                                                  |                                                      |
| product `price`                       | `price`                                                                           |                                                      |
| product `quantity`                    | `quantity`                                                                        |                                                      |
| product `coupon`                      | `coupon`                                                                          |                                                      |
| product `discount`                    | `discount`                                                                        |                                                      |
| product `affiliation`                 | `affiliation`                                                                     |                                                      |
| product `position`                    | `index`                                                                           |                                                      |
| product `currency`                    | `currency`                                                                        |                                                      |
| The product property of the same name | `location_id`, `promotion_id`, `promotion_name`, `creative_name`, `creative_slot` |                                                      |

## Custom events

Any other event is sent under its own name, converted to lowercase with every character other than a letter, number or underscore replaced by `_`, and 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 rules above.

Identify, group and alias events are sent the same way, under the names `identify`, `group` and `alias`, when the **Events** setting lets them through.

## User data

* **`user_id`**: the event's User ID.
* **User properties**: the event's traits (`traits` on identify events, `context.traits` on other events). 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.
* **`session_id`**: the GA4 session ID that the browser captured for your stream, when the event has one.

**Forward Extra Event Properties** adds the event properties that the mapping above doesn't cover to the events in the table. Mapped properties always take precedence. Custom events always send their properties.


---

# 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-measurement-protocol.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.