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

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

These keys apply in both modes.

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:
  - from: plan
    to: dimension1

Cloud mode

These keys apply to events sent in cloud mode.

server_side_identify:
  event_category: user_type
  event_action: User Enriched

User deletion

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.

sample_rate:
  web: "50"

reset_custom_dimensions_on_page:
  web:
    - plan

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.

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:
  web: device
  cloud: cloud

Source types

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

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:

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

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