ga4-events

name	ga4-events
description	GA4 Event Implementation Reference — complete event taxonomy, parameter lists, implementation patterns (gtag.js, GTM, Measurement Protocol), and validation techniques
version	1.0.0
author	Cogny AI
platforms	[]
user-invocable	true
argument-hint	<event name, category, or topic>
allowed-tools	["WebFetch","WebSearch","Bash","Read","Write","mcp__cogny__google_analytics_4__tool_list_account_summaries","mcp__cogny__google_analytics_4__tool_get_property","mcp__cogny__google_analytics_4__tool_list_custom_dimensions","mcp__cogny__google_analytics_4__tool_list_custom_metrics","mcp__cogny__google_analytics_4__tool_list_conversion_events","mcp__cogny__google_analytics_4__tool_list_data_streams","mcp__cogny__google_analytics_4__tool_get_metadata","mcp__cogny__google_analytics_4__tool_run_report","mcp__cogny__google_analytics_4__tool_run_realtime_report"]

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.

---

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.

Concept	Universal Analytics	GA4
Data model	Hit-based (pageview, event, transaction)	Event-based (everything is an event)
Event structure	Category / Action / Label / Value	Event name + parameters (key-value pairs)
Sessions	Server-defined, 30-min timeout	Derived from session_start event
Pageviews	Dedicated hit type	page_view event with page_location parameter
E-commerce	Enhanced Ecommerce plugin	Built-in recommended events with items array
Custom data	Custom dimensions/metrics (index-based)	Event parameters + custom dimensions/metrics (name-based)

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

Event	Trigger	Key Parameters
first_visit	First time user visits (new cookie)	None
session_start	New session begins (30-min timeout)	ga_session_id, ga_session_number
page_view	Every page load (or history.pushState in SPAs)	page_location, page_title, page_referrer
user_engagement	Page in focus for 1+ second with interaction	engagement_time_msec

Mobile (Firebase SDK)

Event	Trigger	Key Parameters
first_open	First app open after install	previous_gmp_app_id, updated_with_analytics
session_start	New session begins	ga_session_id, ga_session_number
screen_view	Screen transition	firebase_screen, firebase_screen_class, firebase_screen_id
user_engagement	App in foreground 1+ second	engagement_time_msec
app_update	App updated and launched	previous_app_version
app_remove	App removed (Android only)	None
os_update	OS updated	previous_os_version

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.

Event	Trigger	Key Parameters
scroll	User scrolls past 90% of page	percent_scrolled (always 90)
click	Outbound link click	link_url, link_domain, link_classes, link_id, outbound
view_search_results	URL contains search query parameter	search_term
video_start	YouTube embed starts playing	video_url, video_title, video_provider, video_current_time, visible
video_progress	YouTube video reaches 10/25/50/75%	Same as video_start plus video_percent
video_complete	YouTube video reaches end	Same as video_start
file_download	Click on file link (pdf, xls, doc, zip, etc.)	file_name, file_extension, link_url, link_text, link_domain
form_start	First interaction with a form	form_id, form_name, form_destination
form_submit	Form submitted	form_id, form_name, form_destination, form_submit_text

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

Recommended Events — All Properties

Event	Parameters
login	method (STRING)
sign_up	method (STRING)
share	method (STRING), content_type (STRING), item_id (STRING)
search	search_term (STRING)
select_content	content_type (STRING), content_id (STRING)

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,             // REQUIRED — total value
  currency: 'USD',           // REQUIRED — ISO 4217
  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, value, and currency. 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

Event	Parameters
earn_virtual_currency	virtual_currency_name (STRING), value (NUMBER)
spend_virtual_currency	virtual_currency_name (STRING), value (NUMBER), item_name (STRING)
level_up	level (NUMBER), character (STRING)
post_score	score (NUMBER, required), level (NUMBER), character (STRING)
tutorial_begin	None
tutorial_complete	None
unlock_achievement	achievement_id (STRING, required)

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:

Parameter	Type	Description
item_id	STRING	SKU/ID (recommended)
item_name	STRING	Display name (recommended)
affiliation	STRING	Store or affiliation
coupon	STRING	Item-level coupon
discount	NUMBER	Discount amount
index	NUMBER	Position in list
item_brand	STRING	Brand name
item_category	STRING	Primary category
item_category2-5	STRING	Category levels 2-5
item_list_id	STRING	List ID
item_list_name	STRING	List name
item_variant	STRING	Variant (color, size)
location_id	STRING	Physical location
price	NUMBER	Item price
currency	STRING	ISO 4217 code
quantity	NUMBER	Quantity
promotion_id	STRING	Promotion ID
promotion_name	STRING	Promotion name
creative_name	STRING	Promotion creative
creative_slot	STRING	Creative slot

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

Limit	Value
Unique event names per property	500
Parameters per event	25
Parameter name length	40 characters
Parameter value (string)	100 characters
User property name length	24 characters
User property value (string)	36 characters
User properties per project	25

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

Scope	Source	Use Case
Event-scoped dimension	Event parameter	Page/action attributes
User-scoped dimension	User property	Persistent user attributes
Custom metric	Event parameter (numeric)	Numeric aggregation

Quotas

Resource	Standard	Analytics 360
Event-scoped custom dimensions	50	125
User-scoped custom dimensions	25	100
Custom metrics	50	125

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), client_id must match existing GA4 cookie, events not in Realtime (30-min delay), cannot trigger first_visit/session_start.

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' });

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 — Burns through the 500-name limit. 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