# Google Analytics Destination Config Reference

Google Analytics (Universal Analytics) is a web analytics destination. RudderStack sends events to Google Analytics’ Measurement Protocol from its servers, or — for web sources — loads Google’s analytics.js library in device mode.

In a Google Analytics destination spec:

type: ga
definition_version: 1

RudderStack has deprecated the Google Analytics destination.

To send events to Google Analytics 4, use the Google Analytics 4 destination type, ga4, instead.

Sample configuration

yaml

version: rudder/v1
kind: destination
metadata:
  name: google-analytics-prod
spec:
  id: google-analytics-prod
  display_name: Google Analytics Production
  type: ga
  definition_version: 1
  enabled: true
  config:
    tracking_id: "{{ .GA_TRACKING_ID }}"
    send_user_id: true
    anonymize_ip: true
    enhanced_ecommerce: true

    dimensions:
      - from: plan
        to: dimension1
    metrics:
      - from: age
        to: metric1
    content_groupings:
      - from: section
        to: contentGroup1

    enable_server_side_identify: true
    server_side_identify:
      event_category: user_type
      event_action: User Enriched

    track_categorized_pages:
      web: true
    track_named_pages:
      web: true
    sample_rate:
      web: "100"
    site_speed_sample_rate:
      web: "1"

    event_filtering:
      blacklist:
        - Cart Viewed

    connection_mode:
      web: device
      cloud: cloud
    consent_management:
      web:
        - provider: oneTrust
          consents:
            - analytics

The above example loads analytics.js on web sources in device mode, where the web-keyed settings apply, and sends server-side events in cloud mode, where enable_server_side_identify lets identify calls through — see Web device mode and Cloud mode.

Config keys

config accepts only the keys listed below. The shared config key rules cover unknown keys, defaults, and immutability.

Google Analytics settings split by connection mode. The groups below say which mode each key affects. Rudder CLI accepts every key whatever the mode — a key for the other mode is stored and ignored.

In cloud mode Google Analytics accepts identify, page, screen, and track. In device mode, web sources send page and track; an identify call sets the user ID and mapped traits on the tracker for later hits, without sending a hit of its own.

Connection

tracking_id

RequiredSecret

Type: string

Description: Tracking ID of your Universal Analytics property, from Admin > Tracking Info > Tracking Code in Google Analytics.

Notes:

UA-, YT-, or MO-, then digits, a hyphen, and up to 100 more digits — for example UA-123456789-1.
A Google Analytics 4 measurement ID (G-…) is rejected. GA4 properties take the ga4 type.
A {{ path || fallback }} template is accepted in place of a literal.
A spec that omits this key fails validation with 'tracking_id' is required.

Supply it as a {{ .VAR }} reference rather than a literal — see Secrets.

See Where can I find the Google Analytics tracking ID?.

Tracking

These keys apply in both modes.

send_user_id

Type: boolean

Default value: false

Description: Send the event’s userId to Google Analytics as the user ID, for identified visitors. The dashboard calls it Send user-id to GA.

See Identify.

anonymize_ip

Type: boolean

Default value: false

Description: Anonymize visitors’ IP addresses.

include_search

Type: boolean

Default value: false

Description: Include the query string in the page path sent with page views. The dashboard calls it Include the Querystring in Page Views.

See Site search.

non_interaction

Type: boolean

Default value: false

Description: Mark every event as a non-interaction hit, which doesn’t count toward bounce rate. An event’s own properties.nonInteraction overrides it.

See Non-interaction events.

enhanced_ecommerce

Type: boolean

Default value: false

Description: Send ecommerce events through Google Analytics enhanced ecommerce. It must be turned on in Google Analytics too.

See Enhanced ecommerce.

enhanced_link_attribution

Type: boolean

Default value: false

Description: Turn on Google Analytics enhanced link attribution, for more detailed reports of the links visitors click. In cloud mode, the link ID comes from the event’s properties.linkid.

double_click

Type: boolean

Default value: false

Description: Turn on Google’s advertising features — remarketing, display ads, and demographic reports. The dashboard calls it Remarketing, Display Ads and Demographic Reports.

Notes:

In web device mode, it loads Google’s display features plugin.
In cloud mode, RudderStack instead marks each hit with the Measurement Protocol’s npa=1, which disables ads personalization for that hit.

Custom dimensions and content groupings

These keys apply in both modes. In each mapping, from and to are each at most 100 characters, or a {{ path || fallback }} template.

dimensions

Type: array of objects

Description: Maps event properties and traits to Google Analytics custom dimensions, which must exist in Google Analytics first.

Notes:

from — event property or trait name.
to — custom dimension, written dimension<index>, such as dimension1.

yaml

dimensions:
  - from: plan
    to: dimension1

See Custom dimensions.

metrics

Type: array of objects

Description: Maps numeric event properties and traits to custom metrics.

Notes:

from — event property or trait name.
to — custom metric, written metric<index>, such as metric1.

content_groupings

Type: array of objects

Description: Maps event properties and traits to content groupings, which group pages together in reports.

Notes:

from — event property or trait name.
to — content grouping, written contentGroup<index>, such as contentGroup1.

See Content groupings.

custom_mappings

Internal

Type: array of objects

Description: An older, combined form of dimensions and metrics. Cloud mode reads it only when neither dimensions nor metrics is set.

Notes:

from — event property or trait name.
to — an entry whose to starts with cd is a custom dimension, and one starting with cm is a custom metric.

The dashboard keeps this field hidden. Rudder CLI accepts it so that a destination already carrying values keeps them. Leave it out of a new destination, and keep whatever rudder-cli import brings back.

Cloud mode

These keys apply to events sent in cloud mode.

enable_server_side_identify

Type: boolean

Default value: false

Description: Send identify calls to Google Analytics as events. When false, identify events sent in cloud mode fail with an error.

server_side_identify

Type: object

Description: Event category and action for the events identify calls become.

Notes:

Applies when enable_server_side_identify is true. Leave it unset otherwise.
event_category — name of the identify trait whose value RudderStack sends as the event category. When the event has no such trait, the category is All.
event_action — event action.
Set both or neither — Rudder CLI rejects one without the other. Omit the block to send the category All and the action User Enriched.
Each is at most 100 characters, or a {{ path || fallback }} template.

yaml

server_side_identify:
  event_category: user_type
  event_action: User Enriched

Despite its name, and the dashboard’s Server Side Identify Event Category label, event_category isn’t the category itself. RudderStack sends the value of the trait it names — event_category: user_type sends each user’s user_type trait.

disable_md5

Type: boolean

Default value: false

Description: Don’t fall back to an MD5 hash of userId for the client ID. The dashboard calls it Disable Md5 encryption from Client ID.

RudderStack takes the client ID from the integrations object, the gaExternalId external ID, traits.cid, or anonymousId, in that order. When none is set, it hashes userId, unless this is true. See How RudderStack takes clientId.

User deletion

rudder_delete_account_id

Type: string

Description: ID of the Google account RudderStack uses to delete users from Google Analytics, for example on a suppress-with-delete regulation. The dashboard calls it Data regulation account, and creates the account when you sign in with Google.

Notes:

Applies whatever the connection mode — deletion runs from RudderStack’s servers.
At most 100 characters, and must not contain line breaks.
A {{ path || fallback }} template is accepted in place of a literal.

User deletion is available only on the Enterprise plan. See Deleting a user.

Web device mode

These keys configure analytics.js in the browser, so they apply only when connection_mode.web is device. Each is an object keyed by web. Where the dashboard has a default, the SDK applies the same value when the key is unset.

track_categorized_pages

Type: object

Description: Also send a non-interaction event for each page call that has a category.

Notes:

web — boolean. Unset means true, the dashboard’s default.

track_named_pages

Type: object

Description: Also send a non-interaction event for each page call that has a name.

Notes:

web — boolean. Unset means true.

use_rich_event_names

Type: object

Description: Name the events that track_categorized_pages and track_named_pages send Viewed <category> Page and Viewed <name> Page — for example Viewed Signup Page.

Notes:

web — boolean.

sample_rate

Type: object

Description: Percentage of users to track.

Notes:

web — a percentage written as a string: "50", not 50. Rudder CLI checks only that it’s at most 100 characters, or a template. Unset means "100".

yaml

sample_rate:
  web: "50"

site_speed_sample_rate

Type: object

Description: Percentage of users whose site speed data is collected.

Notes:

web — a percentage written as a string, on the same terms as sample_rate. Unset means "1".

domain

Type: object

Description: Domain the _ga cookie is set on. The dashboard calls it Cookie Domain Name.

Notes:

web — string, at most 100 characters, or a template. Unset means auto.

optimize

Type: object

Description: Google Optimize container ID. With it set, the SDK loads the Optimize plugin.

Notes:

web — string, at most 100 characters, or a template. Secret — see Secrets.

set_all_mapped_props

Type: object

Description: Set the mapped custom dimensions and metrics on the page, so every later event on that page carries them. When false, they’re sent only with the event they came from. The dashboard calls it Set Custom Dimensions & Metrics to the Page.

Notes:

web — boolean. Unset means true.

reset_custom_dimensions_on_page

Type: object

Description: Properties whose custom dimensions are cleared on each page call, before new values are set. Each name must also appear as a from in dimensions.

Notes:

web — array of property names, each at most 100 characters or a template.

yaml

reset_custom_dimensions_on_page:
  web:
    - plan

named_tracker

Type: object

Description: Send events through a tracker named rudderGATracker instead of the default tracker.

Notes:

web — boolean.

See Named tracker.

use_google_amp_client_id

Type: object

Description: Use the AMP client ID, so users are recognized across AMP and non-AMP pages.

Notes:

web — boolean.

Event filtering

Client-side event filtering is applied by the RudderStack SDK, so it affects only web sources connected in device mode. Rudder CLI accepts the block in any mode, but events sent in cloud mode reach Google Analytics unfiltered.

event_filtering

Type: object

Description: Restricts which track events the SDK passes to Google Analytics, by event name.

Notes:

Applies when connection_mode.web is device. Leave it unset otherwise.
whitelist — array of event names to allow; every other track event is dropped.
blacklist — array of event names to drop; every other track event is allowed.
The two are mutually exclusive, and Rudder CLI enforces it — setting both fails validation.
Each name is at most 100 characters, or a {{ path || fallback }} template.

Per-source keys

Both keys are objects keyed by the local source type — the tokens listed under Source types. A key naming a source type this destination doesn’t support fails validation.

connection_mode

Type: object

Description: Maps each source type you connect to the mode its events reach Google Analytics in, using the modes in Source types.

Notes:

An entry is required for each source type you connect — see Connect a source.
A mode the source type doesn’t support on this destination fails validation — for example device for ios.

yaml

connection_mode:
  web: device
  cloud: cloud

consent_management

Type: object

Description: Consent provider configuration per source type. The entry shape, accepted providers, and the rules on resolution_strategy and consents are shared across all destination types — see Consent management.

Source types

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

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

Only web offers device mode, which loads analytics.js in the browser. See RudderStack Connection Modes.

warehouse is the token a Reverse ETL source 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 — see Manage Reverse ETL Connections using Rudder CLI.

The dashboard additionally offers Google Analytics to AMP and Shopify sources. Rudder CLI doesn’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. Without it:

destination 'google-analytics-prod' config has no 'connection_mode' entry for source type 'web'

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

Secrets

tracking_id and optimize.web are the secret keys. Write each one you use as a {{ .VAR }} reference and supply the value at apply time:

yaml

config:
  tracking_id: "{{ .GA_TRACKING_ID }}"
  optimize:
    web: "{{ .GA_OPTIMIZE_CONTAINER_ID }}"

bash

export RUDDER_GA_TRACKING_ID="..."
export RUDDER_GA_OPTIMIZE_CONTAINER_ID="..."
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.
In web device mode the tracking ID and the Optimize container ID are embedded in the page’s JavaScript, so masking them protects your YAML, not the values themselves.
rudder_delete_account_id only identifies the Google account connected in the dashboard. The account’s credentials stay in RudderStack.

See How to Use Variable Substitution in Rudder CLI.

Changes by release

No changes since this type became available.

For changes across every destination type, see Destination Type Changes by Release.

See more

Google Analytics Destination for event mappings, enhanced ecommerce, client ID handling, and user deletion
Google Analytics 4 Destination Config Reference for the ga4 type that replaces this one
Destination Type Reference for Rudder CLI for the rules shared across destination types
Destination YAML Reference for the spec envelope