GA4 Event Implementation Reference

Complete reference for implementing Google Analytics 4 events: automatically collected, enhanced measurement, recommended, and custom events with exact parameter lists, code examples, and validation techniques.

Full docs: https://cogny.com/docs/ga4-event-implementation

Usage

/ga4-events                          # Show event model overview
/ga4-events purchase                 # Show purchase event parameters and code
/ga4-events ecommerce                # Full e-commerce event funnel reference
/ga4-events enhanced measurement     # Enhanced measurement events list
/ga4-events custom events            # Custom event naming rules and limits
/ga4-events validation               # DebugView, Realtime, and BigQuery checks
/ga4-events gtm                      # GTM dataLayer implementation patterns
/ga4-events measurement protocol     # Server-side Measurement Protocol examples

Instructions

You are a GA4 event implementation expert. Use this reference to help users implement, audit, and validate GA4 events correctly. Provide precise, copy-paste-ready code examples.

When the user asks a question, find the relevant section below and provide actionable answers with ready-to-use code. If GA4 MCP tools are available, use them to inspect the user's actual property configuration (custom dimensions, data streams, conversion events) for context-aware advice.

If the user provides a specific event name or topic as an argument, focus on that area. Otherwise, provide an overview of the event model.

Works with

Works with zero accounts: the reference below is complete on its own. When connected, these make the answer specific to the user's setup:

See "Live validation" under Validation and Debugging.

Event Model Overview

GA4 uses an event-based data model where everything is an event. Unlike Universal Analytics hit types (pageview, event, transaction), GA4 has a single concept: events with parameters.

Every GA4 event has:

• Event name: String identifier (e.g., page_view, purchase)
• Event parameters: Key-value pairs (e.g., page_location, transaction_id)
• User properties: Persistent user attributes (e.g., membership_tier)

Automatically Collected Events

Collected automatically with no configuration. Cannot be disabled.

Web

Mobile (Firebase SDK)

Auto-attached Parameters (every event)

language, page_location, page_referrer, page_title, screen_resolution, ga_session_id, ga_session_number, engagement_time_msec

Enhanced Measurement Events

Collected automatically when enabled in Admin > Data Streams > Enhanced Measurement. Each can be toggled individually.

Note: Video tracking only works with YouTube embeds using enablejsapi=1.

Recommended Events — All Properties

gtag('event', 'login', { method: 'Google' });
gtag('event', 'sign_up', { method: 'Email' });
gtag('event', 'search', { search_term: 'running shoes' });

Recommended Events — E-commerce

Implement in order for full funnel reporting.

view_item_list

gtag('event', 'view_item_list', {
  item_list_id: 'category_123',
  item_list_name: 'Running Shoes',
  items: [{
    item_id: 'SKU_123', item_name: 'Trail Runner Pro', item_brand: 'RunCo',
    item_category: 'Shoes', item_category2: 'Running', item_variant: 'Blue',
    price: 129.99, currency: 'USD', index: 0,
    item_list_id: 'category_123', item_list_name: 'Running Shoes'
  }]
});

select_item

gtag('event', 'select_item', {
  item_list_id: 'category_123', item_list_name: 'Running Shoes',
  items: [{ item_id: 'SKU_123', item_name: 'Trail Runner Pro', price: 129.99, currency: 'USD', index: 0 }]
});

view_item

gtag('event', 'view_item', {
  currency: 'USD', value: 129.99,
  items: [{ item_id: 'SKU_123', item_name: 'Trail Runner Pro', item_brand: 'RunCo',
    item_category: 'Shoes', item_variant: 'Blue', price: 129.99, currency: 'USD', quantity: 1 }]
});

add_to_cart

gtag('event', 'add_to_cart', {
  currency: 'USD', value: 129.99,
  items: [{ item_id: 'SKU_123', item_name: 'Trail Runner Pro', price: 129.99, currency: 'USD', quantity: 1 }]
});

remove_from_cart

gtag('event', 'remove_from_cart', {
  currency: 'USD', value: 129.99,
  items: [{ item_id: 'SKU_123', item_name: 'Trail Runner Pro', price: 129.99, currency: 'USD', quantity: 1 }]
});

view_cart

gtag('event', 'view_cart', {
  currency: 'USD', value: 259.98,
  items: [
    { item_id: 'SKU_123', item_name: 'Trail Runner Pro', price: 129.99, currency: 'USD', quantity: 1 },
    { item_id: 'SKU_456', item_name: 'Road Runner Elite', price: 149.99, currency: 'USD', quantity: 1 }
  ]
});

begin_checkout

gtag('event', 'begin_checkout', {
  currency: 'USD', value: 259.98, coupon: 'SUMMER20',
  items: [
    { item_id: 'SKU_123', item_name: 'Trail Runner Pro', price: 129.99, currency: 'USD', quantity: 1 },
    { item_id: 'SKU_456', item_name: 'Road Runner Elite', price: 149.99, currency: 'USD', quantity: 1 }
  ]
});

add_shipping_info

gtag('event', 'add_shipping_info', {
  currency: 'USD', value: 259.98, coupon: 'SUMMER20', shipping_tier: 'Express',
  items: [{ item_id: 'SKU_123', item_name: 'Trail Runner Pro', price: 129.99, currency: 'USD', quantity: 1 }]
});

add_payment_info

gtag('event', 'add_payment_info', {
  currency: 'USD', value: 259.98, coupon: 'SUMMER20', payment_type: 'Credit Card',
  items: [{ item_id: 'SKU_123', item_name: 'Trail Runner Pro', price: 129.99, currency: 'USD', quantity: 1 }]
});

purchase

gtag('event', 'purchase', {
  transaction_id: 'T12345',  // REQUIRED — unique transaction ID
  value: 259.98,             // sum of price * quantity (no tax/shipping); needed for revenue
  currency: 'USD',           // ISO 4217 — REQUIRED whenever value is set
  tax: 20.80,
  shipping: 9.99,
  coupon: 'SUMMER20',
  items: [
    { item_id: 'SKU_123', item_name: 'Trail Runner Pro', affiliation: 'Online Store',
      coupon: 'ITEM10OFF', discount: 13.00, item_brand: 'RunCo', item_category: 'Shoes',
      item_category2: 'Running', item_variant: 'Blue', price: 129.99, currency: 'USD', quantity: 1 },
    { item_id: 'SKU_456', item_name: 'Road Runner Elite', affiliation: 'Online Store',
      item_brand: 'RunCo', item_category: 'Shoes', price: 149.99, currency: 'USD', quantity: 1 }
  ]
});

Critical: purchase requires transaction_id and items. value is needed for revenue reporting, and currency is required whenever value is set (without it revenue isn't computed). GA4 deduplicates by transaction_id within 72 hours.

refund

// Full refund
gtag('event', 'refund', { transaction_id: 'T12345', value: 259.98, currency: 'USD' });

// Partial refund
gtag('event', 'refund', {
  transaction_id: 'T12345', value: 129.99, currency: 'USD',
  items: [{ item_id: 'SKU_123', price: 129.99, currency: 'USD', quantity: 1 }]
});

Recommended Events — Lead Generation

generate_lead

gtag('event', 'generate_lead', { currency: 'USD', value: 50.00 });

Recommended Events — Gaming

gtag('event', 'earn_virtual_currency', { virtual_currency_name: 'Coins', value: 100 });
gtag('event', 'spend_virtual_currency', { virtual_currency_name: 'Coins', value: 50, item_name: 'Power Boost' });
gtag('event', 'level_up', { level: 5, character: 'Warrior' });
gtag('event', 'post_score', { score: 15000, level: 5, character: 'Warrior' });
gtag('event', 'tutorial_begin');
gtag('event', 'tutorial_complete');
gtag('event', 'unlock_achievement', { achievement_id: 'first_blood' });

Item Parameter Reference

The items array supports these parameters per item:

At least one of item_id or item_name is required. Max 200 items per event.

Custom Events

Use when no automatically collected, enhanced measurement, or recommended event fits.

Naming Rules

• Max 40 characters
• Must start with alphabetic character
• Only [a-zA-Z][a-zA-Z0-9_]*
• Case sensitive — Add_To_Cart and add_to_cart are different events
• Cannot use reserved prefixes: firebase_, google_, ga_
• Cannot use reserved event names (e.g., first_visit, session_start, app_install, in_app_purchase, etc.)

Limits

Examples

gtag('event', 'newsletter_signup', {
  newsletter_type: 'weekly_digest', signup_location: 'footer'
});

gtag('event', 'feature_used', {
  feature_name: 'export_csv', feature_category: 'data_tools', plan_tier: 'pro'
});

gtag('event', 'article_read', {
  article_id: 'post_12345', article_category: 'technology', read_time_seconds: 245
});

Custom Dimensions and Metrics

Register event parameters or user properties for reporting in Admin > Custom definitions.

Scoping

Quotas

Processing time: 24-48 hours for standard reports (immediate in Realtime/DebugView).

// Set user properties
gtag('set', 'user_properties', {
  membership_tier: 'gold', signup_date: '2025-01-15'
});

GTM dataLayer Implementation

// Custom event
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
  event: 'newsletter_signup',
  newsletter_type: 'weekly_digest',
  signup_location: 'footer'
});

// E-commerce — ALWAYS clear ecommerce first
window.dataLayer.push({ ecommerce: null });
window.dataLayer.push({
  event: 'purchase',
  ecommerce: {
    transaction_id: 'T12345', value: 259.98, currency: 'USD',
    tax: 20.80, shipping: 9.99, coupon: 'SUMMER20',
    items: [{ item_id: 'SKU_123', item_name: 'Trail Runner Pro',
      item_brand: 'RunCo', item_category: 'Shoes', price: 129.99, quantity: 1 }]
  }
});

Measurement Protocol (Server-Side)

POST https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXXXXX&api_secret=YOUR_API_SECRET

{
  "client_id": "abc123.def456",
  "events": [{
    "name": "offline_purchase",
    "params": {
      "transaction_id": "OFFLINE_T789",
      "value": 250.00,
      "currency": "USD"
    }
  }]
}

import requests, json

url = 'https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXXXXX&api_secret=YOUR_API_SECRET'
payload = {
    'client_id': 'abc123.def456',
    'events': [{'name': 'offline_purchase', 'params': {
        'transaction_id': 'OFFLINE_T789', 'value': 250.00, 'currency': 'USD'
    }}]
}
response = requests.post(url, data=json.dumps(payload))

Limitations: No response validation (use debug endpoint); events are joined to online activity via client_id / app_instance_id, so reuse the real _ga client ID; include session_id (within 24 hours of session start) to tie the event to a session; reserved names like first_visit/session_start can't be sent. MP is meant to supplement gtag/GTM/Firebase, not replace them. MP events do show in Realtime within seconds; add debug_mode: 1 and engagement_time_msec to see them in DebugView.

Validation Server

POST https://www.google-analytics.com/debug/mp/collect?measurement_id=G-XXXXXXXXXX&api_secret=YOUR_API_SECRET
# Returns validation errors instead of silently accepting

Validation and Debugging

DebugView

Enable debug mode to see events in near real-time in Admin > DebugView:

gtag('config', 'G-XXXXXXXXXX', { debug_mode: true });
// Or per-event:
gtag('event', 'purchase', { debug_mode: true, transaction_id: 'T12345', value: 99.99, currency: 'USD' });

Live validation (enhanced when connected)

If Cogny isn't connected, skip this and note what connecting adds.

1. GA4: tool_run_realtime_report (property_id, metrics: [eventCount],

dimensions: [eventName]) right after a test, then tool_run_report over 7 days with dimensions: [eventName] to see steady-state volume.

1. Segment (if the site sends through Segment): get_events_volume (start_time,

end_time, group_by: [eventName], or event_name: "Order Completed"). Events in Segment but missing in GA4 mean the GA4 destination mapping is wrong, not the site code.

1. Name drift: Segment list_tracking_plan_rules (tracking_plan_id from

list_tracking_plans) and PostHog list_event_definitions (project_id, search). Map each to its GA4 name in one table (Segment Order Completed → purchase, Product Added → add_to_cart) and flag actions with no GA4 equivalent.

1. GrowthBook exposures: list_experiments (status: running) gives each test's

tracking key. GA4 should receive experiment_viewed with experiment_id = that key and variation_id; register both as event-scoped custom dimensions, or the GA4 split is invisible.

Name the tool on every count; Segment counts calls, GA4 counts events after its own filters.

BigQuery Validation Queries

Event volume audit:

SELECT event_name, COUNT(*) as event_count, COUNT(DISTINCT user_pseudo_id) as unique_users
FROM `project.analytics_123456789.events_*`
WHERE _TABLE_SUFFIX = FORMAT_DATE('%Y%m%d', CURRENT_DATE() - 1)
GROUP BY event_name ORDER BY event_count DESC

Missing purchase parameters:

SELECT 'missing_transaction_id' as issue, COUNT(*) as count
FROM `project.analytics_123456789.events_*`
WHERE _TABLE_SUFFIX = FORMAT_DATE('%Y%m%d', CURRENT_DATE() - 1)
  AND event_name = 'purchase'
  AND (SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'transaction_id') IS NULL
UNION ALL
SELECT 'missing_currency', COUNT(*)
FROM `project.analytics_123456789.events_*`
WHERE _TABLE_SUFFIX = FORMAT_DATE('%Y%m%d', CURRENT_DATE() - 1)
  AND event_name = 'purchase'
  AND (SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'currency') IS NULL

Duplicate transactions:

SELECT transaction_id, COUNT(*) as dupes
FROM (
  SELECT (SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'transaction_id') as transaction_id
  FROM `project.analytics_123456789.events_*`
  WHERE _TABLE_SUFFIX BETWEEN FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY))
                          AND FORMAT_DATE('%Y%m%d', CURRENT_DATE() - 1)
    AND event_name = 'purchase'
)
WHERE transaction_id IS NOT NULL
GROUP BY transaction_id HAVING COUNT(*) > 1
ORDER BY dupes DESC

Naming convention audit:

SELECT event_name, COUNT(*) as event_count,
  CASE
    WHEN LENGTH(event_name) > 40 THEN 'exceeds_40_chars'
    WHEN REGEXP_CONTAINS(event_name, r'^(firebase_|google_|ga_)') THEN 'reserved_prefix'
    WHEN NOT REGEXP_CONTAINS(event_name, r'^[a-zA-Z][a-zA-Z0-9_]*$') THEN 'invalid_characters'
    WHEN event_name != LOWER(event_name) THEN 'mixed_case_warning'
    ELSE 'valid'
  END as naming_issue
FROM `project.analytics_123456789.events_*`
WHERE _TABLE_SUFFIX = FORMAT_DATE('%Y%m%d', CURRENT_DATE() - 1)
GROUP BY event_name HAVING naming_issue != 'valid'

Parameter truncation check:

SELECT event_name, ep.key, MAX(LENGTH(ep.value.string_value)) as max_len,
  COUNTIF(LENGTH(ep.value.string_value) >= 100) as at_limit
FROM `project.analytics_123456789.events_*`, UNNEST(event_params) as ep
WHERE _TABLE_SUFFIX = FORMAT_DATE('%Y%m%d', CURRENT_DATE() - 1)
  AND ep.value.string_value IS NOT NULL
GROUP BY 1, 2 HAVING max_len >= 100

Common Pitfalls

1. Case sensitivity — Purchase != purchase. Always use snake_case.
2. String truncation at 100 chars — URLs and long values get silently cut.
3. Custom dimension quotas — 50 event-scoped, 25 user-scoped (standard). Plan carefully.
4. Duplicate purchases — Always include transaction_id for dedup (72-hour window).
5. Missing currency — value without currency is ignored in monetization reports.
6. Stale dataLayer — Always push { ecommerce: null } before ecommerce events in GTM.
7. PII in parameters — No emails, phone numbers, or names. Violates GA4 ToS.
8. Dynamic event names — Fragments reporting (and burns the 500-name limit on app streams). Use parameters instead.

Resources

• GA4 Event Reference: https://developers.google.com/analytics/devguides/collection/ga4/reference/events
• Recommended Events: https://support.google.com/analytics/answer/9267735
• Measurement Protocol: https://developers.google.com/analytics/devguides/collection/protocol/ga4
• Enhanced Measurement: https://support.google.com/analytics/answer/9216061
• Event Limits & Quotas: https://support.google.com/analytics/answer/9267744
• Full Cogny Docs: https://cogny.com/docs/ga4-event-implementation