# Google Analytics 4 Destination Config Reference


> Complete Rudder CLI reference for the Google Analytics 4 destination config keys, gtag and Firebase clients, hybrid mode, web SDK settings, and secrets.



[Google Analytics 4](https://www.rudderstack.com/docs/destinations/streaming-destinations/google-analytics-4/setup-guide/) is a web and app analytics destination. RudderStack sends events to GA4's Measurement Protocol from its servers, loads Google's own SDKs in device mode, or — for web — splits the two in hybrid mode.

In a Google Analytics 4 destination spec:

- `type: ga4`
- `definition_version: 1`

## Sample configuration

```yaml
version: rudder/v1
kind: destination
metadata:
  name: ga4-prod
spec:
  id: ga4-prod
  display_name: Google Analytics 4 Production
  type: ga4
  definition_version: 1
  enabled: true
  config:
    api_secret: "{{ .GA4_API_SECRET }}"
    client_type: gtag
    measurement_id: "{{ .GA4_MEASUREMENT_ID }}"

    debug_mode: false
    pii_properties_to_ignore:
      - pii_property: email
      - pii_property: phone

    capture_page_view:
      web: rs
    debug_view:
      web: false
    extend_page_view_params:
      web: true
    override_client_and_session_ids:
      web: true

    connection_mode:
      web: hybrid
      cloud: cloud
    consent_management:
      web:
        - provider: oneTrust
          consents:
            - analytics
```

The above example uses the gtag client with web sources in `hybrid` mode, which is where `override_client_and_session_ids` applies — see [Web SDK settings](#web-sdk-settings).

## Config keys

`config` accepts only the keys listed below. The [shared config key rules](https://www.rudderstack.com/docs/rudder-cli/destination-types/#config-key-rules) cover unknown keys, defaults, and immutability.

**Info:** In `cloud` mode GA4 accepts `track`, `group`, and `page` events. In `device` mode, web sources send `identify`, `track`, `page`, and `group`, and Android and iOS sources send `identify`, `track`, and `screen`. In `hybrid` mode, `page` goes through device mode and everything else through cloud mode.

### Connection

<div class="rs-ckeys">
<div class="rs-ckey" id="api_secret">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">api_secret</p>RequiredSecret</div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Measurement Protocol API secret of your GA4 data stream, from <strong>Admin</strong> &gt; <strong>Data Streams</strong> &gt; your stream &gt; <strong>Measurement Protocol API secrets</strong>.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>At most 100 characters, and must not contain line breaks.</li>
<li>A <code>{{ path || fallback }}</code> template is accepted in place of a literal.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  See <a href="https://www.rudderstack.com/docs/destinations/streaming-destinations/google-analytics-4/setup-guide/#how-do-i-obtain-the-api-secret" >How do I obtain the API Secret?</a>.
</div>

</div>

<div class="rs-ckey" id="client_type">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">client_type</p>Required</div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Which Google client the data stream uses — gtag for websites, Firebase for apps.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>gtag</code> — needs <code>measurement_id</code>. <code>hybrid</code> mode needs <code>gtag</code>, but Rudder CLI doesn&rsquo;t check it: <code>client_type: firebase</code> with <code>web: hybrid</code> validates.</li>
<li><code>firebase</code> — needs <code>firebase_app_id</code>.</li>
<li>Templates aren&rsquo;t accepted.</li>
<li>The dashboard defaults this field to <code>gtag</code>. Rudder CLI requires it explicitly.</li>
<li>A spec that omits this key fails validation.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="measurement_id">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">measurement_id</p>RequiredSecret</div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Measurement ID of your GA4 web data stream, from <strong>Admin</strong> &gt; <strong>Data Streams</strong> &gt; your stream.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Required when <code>client_type</code> is <code>gtag</code>. Leave it unset otherwise.</li>
<li>Must start with <code>G-</code>, followed by 1 to 100 characters.</li>
<li>A <code>{{ path || fallback }}</code> template is accepted in place of a literal.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  See <a href="https://www.rudderstack.com/docs/destinations/streaming-destinations/google-analytics-4/setup-guide/#how-do-i-obtain-the-measurement-id" >How do I obtain the Measurement Id?</a>.
</div>

</div>

<div class="rs-ckey" id="firebase_app_id">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">firebase_app_id</p>Required</div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Firebase App ID of your GA4 app data stream.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Required when <code>client_type</code> is <code>firebase</code>. Leave it unset otherwise.</li>
<li>At most 100 characters, and must not contain line breaks.</li>
<li>A <code>{{ path || fallback }}</code> template is accepted in place of a literal.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  See <a href="https://www.rudderstack.com/docs/destinations/streaming-destinations/google-analytics-4/setup-guide/#how-do-i-obtain-the-firebase-app-id" >How do I obtain the Firebase App ID?</a>.
</div>

</div>

</div>

### Event handling

<div class="rs-ckeys">
<div class="rs-ckey" id="debug_mode">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">debug_mode</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>boolean</code>
  </p><p class="rs-ckey__field">
    Default value:
    <code>false</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Send cloud-mode events to GA4&rsquo;s validation server instead of reporting them, so you can check validation responses in Live Events. Events sent this way don&rsquo;t appear in reports.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Applies to events sent in <code>cloud</code> mode, including the cloud half of <code>hybrid</code> mode.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="pii_properties_to_ignore">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">pii_properties_to_ignore</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>array of objects</code>
  </p>
<p class="rs-ckey__field">
  Description:
  User traits RudderStack drops before sending events to GA4 — for example email addresses and phone numbers.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>pii_property</code> — the trait name. At most 100 characters, or a <code>{{ path || fallback }}</code> template.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  <div class="rs-code">
  <div class="rs-code__head">yaml<button class="rs-code__copy" type="button">
      
      Copy
    </button>
  </div>
  <div class="highlight"><pre class="chroma"><code class="language-yaml" data-lang="yaml">pii_properties_to_ignore:
  - pii_property: email</code></pre></div>
</div><p>See <a href="https://www.rudderstack.com/docs/destinations/streaming-destinations/google-analytics-4/setup-guide/#how-can-i-prevent-rudderstack-from-sending-pii-fields-to-google-analytics-4" >How can I prevent RudderStack from sending PII fields to Google Analytics 4?</a>.</p>
</div>

</div>

</div>

### Web SDK settings

These keys configure gtag in the browser, so they apply only when `connection_mode.web` is `device` or `hybrid`. The four objects are keyed by `web`.

<div class="rs-ckeys">
<div class="rs-ckey" id="sdk_base_url">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">sdk_base_url</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Custom domain that serves gtag, loaded as <code>https://&lt;domain&gt;/gtag/js</code>. When omitted, <code>https://www.googletagmanager.com</code> is used.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Applies when <code>connection_mode.web</code> is <code>device</code> or <code>hybrid</code>.</li>
<li>Must be a domain URL, and any value containing <code>.ngrok.io</code> is rejected. Rudder CLI checks the format only when <code>client_type</code> is <code>gtag</code> and <code>connection_mode.web</code> is <code>device</code>.</li>
<li>A <code>{{ path || fallback }}</code> template is accepted in place of a literal.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="server_container_url">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">server_container_url</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  URL of your GA4 server-side Google Tag Manager container.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Applies when <code>connection_mode.web</code> is <code>device</code> or <code>hybrid</code>.</li>
<li>Not validated locally.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="capture_page_view">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">capture_page_view</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  How page views reach GA4.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — <code>rs</code> (default) to send them from RudderStack&rsquo;s <code>page</code> calls, or <code>gtag</code> to use GA4 Enhanced Measurement&rsquo;s automatic collection on each page load.</li>
<li>Rudder CLI fills in the default only when the <code>capture_page_view</code> block is present. Omit the block and no value is sent.</li>
<li>Make sure your GA4 measurement configuration matches this setting.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="debug_view">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">debug_view</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Show device-mode events in GA4&rsquo;s <a href="https://support.google.com/analytics/answer/7201382" >DebugView</a>. In <code>hybrid</code> mode that covers the <code>page</code> calls only.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — boolean. The dashboard defaults it to <code>true</code>; Rudder CLI doesn&rsquo;t fill it in.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="extend_page_view_params">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">extend_page_view_params</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Add <code>url</code> and <code>search</code> to the properties sent with each page view. GA4 limits unique properties per event name, so weigh this against your other properties.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — boolean.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="override_client_and_session_ids">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">override_client_and_session_ids</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Replace gtag&rsquo;s <code>client_id</code> and <code>session_id</code> with RudderStack&rsquo;s <code>anonymousId</code> and <code>session_id</code>, so <code>page</code> calls from the browser and other calls from the server stitch into the same sessions.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Applies when <code>connection_mode.web</code> is <code>hybrid</code>. Leave it unset otherwise.</li>
<li><code>web</code> — boolean.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  <strong>Warning:</strong> Switching an existing device-mode setup to <code>hybrid</code> with this on can briefly spike session counts. See <a href="https://www.rudderstack.com/docs/destinations/streaming-destinations/google-analytics-4/setup-guide/#connection-mode-comparison" >Connection mode comparison</a> for the alternative.
</div>

</div>

</div>

### Event filtering

**Warning:** [Client-side event filtering](https://www.rudderstack.com/docs/sources/event-streams/sdks/event-filtering/) applies only to sources connected in `device` mode — web, Android, or iOS. The dashboard shows these controls only then, and the SDK is what applies the filter. Rudder CLI accepts the block in any mode, but it has no effect on cloud-mode connections.

<div class="rs-ckeys">
<div class="rs-ckey" id="event_filtering">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">event_filtering</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Restricts which <code>track</code> events the SDK passes to GA4, by event name.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>whitelist</code> — array of event names to allow; every other <code>track</code> event is dropped.</li>
<li><code>blacklist</code> — array of event names to drop; every other <code>track</code> event is allowed.</li>
<li>The two are mutually exclusive, and Rudder CLI enforces it — setting both fails validation.</li>
<li>Each name is at most 100 characters, or a <code>{{ path || fallback }}</code> template.</li>
</ul>

</div>

</div>

</div>

### Per-source keys

Both keys are objects keyed by the local source type — the tokens listed under [Source types](#source-types). A key naming a source type this destination doesn't support fails validation.

<div class="rs-ckeys">
<div class="rs-ckey" id="connection_mode">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">connection_mode</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Maps each source type you connect to the mode its events reach GA4 in, using the modes in <a href="#source-types" >Source types</a>.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>An entry is required for each source type you connect — see <a href="#connect-a-source" >Connect a source</a>.</li>
<li>A mode the source type doesn&rsquo;t support on this destination fails validation — for example <code>hybrid</code> for <code>android</code>.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  <div class="rs-code">
  <div class="rs-code__head">yaml<button class="rs-code__copy" type="button">
      
      Copy
    </button>
  </div>
  <div class="highlight"><pre class="chroma"><code class="language-yaml" data-lang="yaml">connection_mode:
  web: hybrid
  android: device
  cloud: cloud</code></pre></div>
</div>
</div>

</div>

<div class="rs-ckey" id="consent_management">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">consent_management</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Consent provider configuration per source type. The entry shape, accepted providers, and the rules on <code>resolution_strategy</code> and <code>consents</code> are shared across all destination types — see <a href="https://www.rudderstack.com/docs/rudder-cli/destination-types/#consent-management" >Consent management</a>.
</p>

</div>

</div>

## Source types

Google Analytics 4 accepts events from these source types in the mentioned connection modes:

| Source type | Connection mode |
| :-----| :-----|
| `android` | `cloud`, `device` |
| `android_kotlin` | `cloud` |
| `ios` | `cloud`, `device` |
| `ios_swift` | `cloud` |
| `web` | `cloud`, `device`, `hybrid` |
| `unity` | `cloud` |
| `react_native` | `cloud` |
| `flutter` | `cloud` |
| `cordova` | `cloud` |
| `cloud` | `cloud` |
| `warehouse` | `cloud` |

`web`, `android`, and `ios` offer `device` mode, and `web` alone offers `hybrid`, which needs `client_type: gtag`. See [Connection mode comparison](https://www.rudderstack.com/docs/destinations/streaming-destinations/google-analytics-4/setup-guide/#connection-mode-comparison) and [Google Analytics 4 Hybrid Mode](https://www.rudderstack.com/docs/destinations/streaming-destinations/google-analytics-4/hybrid-mode/).

`warehouse` is the token a [Reverse ETL source](https://www.rudderstack.com/docs/sources/reverse-etl/) resolves to. Rudder CLI manages the destination’s `warehouse` entry — if the destination is connected to a Reverse ETL source, set `connection_mode.warehouse: cloud` in its spec, or `apply` removes it.

Rudder CLI can also declare the Reverse ETL connection itself, for the types listed under [Supported destinations](https://www.rudderstack.com/docs/rudder-cli/yaml-retl-connections/#supported-destinations) — see [Manage Reverse ETL Connections using Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/retl-connections/).

**Info:** The dashboard additionally offers Google Analytics 4 to AMP and Shopify sources. Rudder CLI doesn&#39;t manage those connections, so `amp` and `shopify` are invalid here.

## Connect a source

An event stream connection to this destination is checked against two rules at `validate` time.

**The source's type must be supported.** A source's type resolves to one of the tokens above before the check — a JavaScript source resolves to `web`, and webhook and server-side SDK sources resolve to `cloud`. Every type an event stream source can resolve to is supported here, so this check always passes.

**The destination config must carry a `connection_mode` entry for that source type.** This lives on the destination spec, not on the [connection spec](https://www.rudderstack.com/docs/rudder-cli/yaml-connections/). Without it:

```text
destination 'ga4-prod' config has no 'connection_mode' entry for source type 'web'
```

Google Analytics 4 needs no additional config keys to connect a source of any type, in any mode.

## Secrets

`api_secret` and `measurement_id` are the secret keys. Write each as a `{{ .VAR }}` reference and supply the value at apply time:

```yaml
config:
  api_secret: "{{ .GA4_API_SECRET }}"
  measurement_id: "{{ .GA4_MEASUREMENT_ID }}"
```

```bash
export RUDDER_GA4_API_SECRET="..."
export RUDDER_GA4_MEASUREMENT_ID="G-XXXXXXXXXX"
rudder-cli apply

# or
rudder-cli apply --var-file secrets.vars.yaml
```

Note that:

- `rudder-cli import` writes only the secrets the API returns, as `{{ .VAR }}` references, and leaves the others out. Add any secret key it leaves out, then supply the variables before you apply — see [Secrets](https://www.rudderstack.com/docs/rudder-cli/destination-types/#secrets).
- In device and hybrid mode the measurement ID is embedded in the page's JavaScript, so masking it protects your YAML, not the value itself.
- `firebase_app_id` isn't a secret and is imported as-is.

See [How to Use Variable Substitution in Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/variable-substitution/).

## Changes by release

<table>
  <thead>
    <tr>
      <th>Version</th>
      <th>Change</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>v0.29.0</td>
      <td><strong>Breaking:</strong> A <code>null</code> config value, written as <code>key: null</code>, <code>key: ~</code>, or <code>key:</code> with no value, fails <code>validate</code> with <code>'&lt;key&gt;' must not be null; set a value or remove the key</code>. Earlier releases accepted it: a top-level null planned an update on every <code>apply</code>, and a null inside a list item failed at the API.<br><strong>What to do:</strong> Remove the key to leave it unset, or give it a value.</td>
    </tr>
    <tr>
      <td>v0.29.0</td>
      <td><strong>Breaking:</strong> An empty string, <code>&quot;&quot;</code>, on a key that takes one of a fixed set of values fails <code>validate</code> with <code>'&lt;key&gt;' must be one of [...]</code>, unless <code>&quot;&quot;</code> is one of the key&rsquo;s values. Earlier releases accepted it, and the API rejected it at <code>apply</code>.<br><strong>What to do:</strong> Remove the key to leave it unset, or set one of the listed values.</td>
    </tr>
    <tr>
      <td>v0.29.0</td>
      <td><strong>Changed:</strong> <code>validate</code> warns when a secret key holds anything but one <code>{{ .VAR }}</code> reference with no default, and when one variable fills two secret keys. It also masks secret values in the lines it prints.</td>
    </tr>
    <tr>
      <td>v0.29.0</td>
      <td><strong>Changed:</strong> <code>rudder-cli import</code> writes each secret reference single-quoted, as <code>'{{ .VAR }}'</code>, so a value containing double quotes, like a JSON key file, substitutes as a string. A single quote in a value that fills such a reference is written as <code>''</code>.<br><strong>What to do:</strong> In a spec imported by an earlier release, quote each reference to a JSON value by hand: <code>'{{ .VAR }}'</code>.</td>
    </tr>
    <tr>
      <td>v0.29.0</td>
      <td><strong>Changed:</strong> <code>validate</code> reports a value of the wrong type once per key, such as <code>'email' must be a string</code>, instead of one raw decoding error.</td>
    </tr>
    <tr>
      <td>v0.28.0</td>
      <td><strong>Added:</strong> <code>warehouse</code> source type, for destinations connected to a Reverse ETL source. Set <code>connection_mode.warehouse: cloud</code> for such a destination, or <code>apply</code> removes the entry.</td>
    </tr>
  </tbody>
</table>

For changes across every destination type, see [Destination Type Changes by Release](https://www.rudderstack.com/docs/rudder-cli/destination-types/changes/).

## See more

- [Google Analytics 4 Destination](https://www.rudderstack.com/docs/destinations/streaming-destinations/google-analytics-4/setup-guide/) for obtaining the IDs and choosing a connection mode
- [Destination Type Reference for Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/destination-types/) for the rules shared across destination types
- [Destination YAML Reference](https://www.rudderstack.com/docs/rudder-cli/yaml-destinations/) for the spec envelope