Web Analytics
GA4 Custom Events: Setup, Key Events and Tracking Plan
EyeCaptain

GA4 Custom Events: Setup, Key Events and Tracking Plan

GA4 custom events step by step: gtag.js and GTM snippets, tracking plans for lead gen and ecommerce, custom dimensions, key events and DebugView testing.

11 min read
177 views
GA4 custom events guide 2026Google Analytics 4 conversion trackingecommerce event tracking secrets

A GA4 custom event is an event you name and send yourself, using gtag('event', 'your_event_name', {...}), a Google Tag Manager GA4 Event tag, or the "Create event" feature in the GA4 admin. You need one only when an action is not already covered by GA4's automatically collected, enhanced measurement or recommended events. To make it useful for conversion tracking, register its parameters as custom dimensions and mark it as a key event, which is what GA4 has called conversions since 2024.

What are GA4 custom events, and when do you actually need one?

Every interaction GA4 records is an event, and Google sorts them into four groups. Check them in this order before creating anything new.

TypeWho defines itExamplesSetup needed
Automatically collectedGooglefirst_visit, session_start, user_engagementNone. They come with the Google tag.
Enhanced measurementGooglepage_view, scroll, click (outbound), view_search_results, video_start, file_download, form_start, form_submitToggle in Admin, Data streams, Enhanced measurement
RecommendedGoogle names them, you send themgenerate_lead, sign_up, login, add_to_cart, begin_checkout, purchaseCode or GTM, using Google's exact names and parameters
CustomYoupricing_toggle, form_error, size_guide_openCode, GTM or the GA4 UI

A decision rule

  1. If GA4 already records the action automatically or through enhanced measurement, use that event.
  2. If Google publishes a recommended event for it (see Google's recommended events reference), send that name with the recommended parameters. Recommended events plug into built-in reports such as the ecommerce reports, and custom names do not.
  3. Only if neither exists, create a custom event.

For conversion work, custom events are usually friction signals no standard event describes: a form validation error, a pricing toggle, a failed coupon code. They explain why the main conversion rate moves.

What are the GA4 event limits you must design around?

Google's "[GA4] Event collection limits" and configuration limits help pages set these rules. GA4 silently drops events and parameters that exceed them.

  • Event name: up to 40 characters.
  • Parameters per event: up to 25.
  • Parameter name: up to 40 characters. Parameter value: up to 100 characters (page_title, page_referrer and page_location have longer limits).
  • Distinct event names: no limit for web data streams, according to Google's collection limits page. App streams have a cap of 500.
  • Custom dimensions per standard property: 50 event-scoped, 25 user-scoped, 10 item-scoped (Analytics 360 allows more).
  • Key events: up to 30 per standard property and 50 per Analytics 360 property, per Google's "Mark events as key events" page.
  • Events created or modified in the UI: up to 50 of each per property, per Google's "Rename and generate new events" page.

The custom dimension quota is the one you will hit first. Unregistered parameters still reach BigQuery exports but not reports or explorations, so spend the 50 slots on parameters you will segment by.

How do you build a GA4 event tracking plan?

A tracking plan is one shared table: event name, what fires it, what context it carries, and which decision it informs. If you cannot fill in the last column, drop the event.

Tracking plan for a lead generation site

Event nameTriggerParametersWhy it matters for CRO
generate_lead (recommended)Server confirms the form was acceptedform_id, lead_type, value, currencyThe primary key event. Value lets you compare channels by lead worth, not just volume.
form_error (custom)Client-side validation failsform_id, field_name, error_typeShows which field blocks completions. Pair with your form labels and error message copy.
cta_click (custom)Click on a primary call-to-action buttoncta_location, cta_textCompares hero, mid-page and footer CTAs on the same page.
pricing_toggle (custom)User switches monthly/annual billingbilling_periodShows price sensitivity before the demo request.
meeting_booked (custom)Scheduler confirmation callbackmeeting_typeSeparates form fills from booked calls, which are worth more.
click_to_call (custom)Click on a tel: linkcta_locationPhone leads are invisible without it, especially on mobile.

Tracking plan for an ecommerce site

Event nameTriggerParametersWhy it matters for CRO
view_item (recommended)Product page loadcurrency, value, itemsStart of the product-to-purchase funnel.
add_to_cart (recommended)Item added successfullycurrency, value, itemsProduct page effectiveness: add_to_cart divided by view_item.
begin_checkout, add_shipping_info, add_payment_info (recommended)Each checkout step completedcurrency, value, items, shipping_tier or payment_typeLocates the step where buyers leave. Feeds GA4 funnel exploration for checkout.
purchase (recommended)Order confirmation, once per ordertransaction_id, value, currency, itemsRevenue. GA4 marks it as a key event by default.
coupon_error (custom)Coupon code rejectederror_typeInvalid codes are a known checkout exit point and easy to fix.
size_guide_open (custom)Size guide openeditem_categoryHigh rates point to unclear fit information on the product page.

If you run either type of site, the lead generation and ecommerce solution pages list the page-level issues these events usually point to.

Illustration 1: GA4 Custom Events: Setup, Key Events and Tracking PlanEyeCaptain

What naming conventions should GA4 custom events follow?

Google's "Event naming rules" page sets the hard rules: names are case sensitive, must start with a letter, and may contain only letters, numbers and underscores. Some names and prefixes are reserved (for example names starting with google_, ga_ or firebase_). On top of those rules, use these conventions:

  • snake_case, all lowercase. Form_Error and form_error are two different events in GA4, and they will split your data.
  • object_action order, matching Google's own style: form_error, coupon_apply, video_complete.
  • Generic event, specific parameter. Send one form_error event with a form_id parameter, not contact_form_error and demo_form_error. This saves event names and keeps reports comparable.
  • No dynamic values in event names. Never build names like click_button_3482. IDs belong in parameters, and only if you need them.

How do you create custom events in GA4?

Code and GTM send new events from the browser. The GA4 UI method only derives new events from ones GA4 already receives.

Method 1: gtag.js

If the Google tag (gtag.js) is installed directly on the site, call gtag('event', ...) at the moment the action succeeds. For a lead form, that is after the server confirms the submission, not on the button click.

gtag('event', 'generate_lead', {
  form_id: 'demo_request',
  lead_type: 'demo',
  value: 50,
  currency: 'USD'
});

A custom event uses the same syntax:

gtag('event', 'form_error', {
  form_id: 'demo_request',
  field_name: 'work_email',
  error_type: 'invalid_format'
});

Method 2: GTM GA4 custom event (dataLayer.push and a GA4 Event tag)

The site pushes a message to the data layer and GTM decides what to send to GA4.

  1. Push the event from the site. Your developer adds this where the action succeeds:
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({
      event: 'form_error',
      form_id: 'demo_request',
      field_name: 'work_email',
      error_type: 'invalid_format'
    });
  2. Create Data Layer Variables. In GTM, go to Variables, New, Data Layer Variable. Create one each for form_id, field_name and error_type, with the Data Layer Variable Name matching the key exactly.
  3. Create a Custom Event trigger. Triggers, New, Custom Event. Set Event name to form_error (case sensitive), firing on All Custom Events.
  4. Create the GA4 Event tag. Tags, New, Google Analytics: GA4 Event. Enter your Measurement ID (G-XXXXXXX), set Event Name to form_error, and add three Event Parameters rows that map each parameter name to its Data Layer Variable.
  5. Attach the trigger from step 3 and save.
  6. Test in Preview mode (see the testing section below), then Submit and Publish the container.

A Google tag with the same Measurement ID must also fire on all pages, or the event tag will have no configuration to send to.

Method 3: "Create event" in the GA4 UI

Go to Admin, Data display, Events, Create event, then Create. Give the new event a name and add matching conditions, for example:

EyeCaptainEyeCaptain
Conversions Booster

Users decide in 3 seconds — are you losing them?

If your page doesn't hook visitors instantly, they're gone. Get a full breakdown of what's causing friction above the fold.

Slow LCP detected

  • event_name equals page_view
  • page_location contains /thank-you/demo

Tick "Copy parameters from the source event" to keep page data. It is the fastest route to a lead event without a developer, but Google states created events do not apply to historical data, it cannot see interactions GA4 does not already receive, and a thank-you page event fires again on every refresh. Use it as a stopgap.

Illustration 2: GA4 Custom Events: Setup, Key Events and Tracking PlanEyeCaptain

How do you register GA4 custom event parameters as custom dimensions?

GA4 collects your parameters, but it shows them in reports only after you register them.

  1. Go to Admin, Data display, Custom definitions, Create custom dimension.
  2. Enter a readable Dimension name, such as "Form field".
  3. Choose Scope: Event for parameters like field_name or cta_location. Use User scope only for stable user attributes, such as plan type, sent as user properties.
  4. Type the Event parameter exactly as sent (field_name). If the event has already been received, you can pick the parameter from the dropdown.
  5. Save. Registration is not retroactive, so data appears only from that point forward.

Register parameters the day tracking goes live, or the gap is lost to reports for good.

How do you mark GA4 key events (formerly conversions)?

In 2024 Google renamed "conversions" in GA4 to key events. Google's "Mark events as key events" page explains that events previously labeled as conversions in Analytics were reclassified as key events. The word "conversion" now refers to the Google Ads side: a key event you import into Google Ads becomes a conversion there. How events are collected did not change, and existing setups needed no code changes.

To mark an event:

  1. Admin, Data display, Events. Find the event and click the star icon ("Mark as key event").
  2. If the event has not been received yet, go to Admin, Data display, Key events, New key event, and type the exact event name.
  3. Choose the counting method. Google's "About key event counting method" page offers once per event (recommended) or once per session. Use once per session for leads, where three submissions in one visit usually mean one person retrying.

Mark only events that represent business value: generate_lead, meeting_booked and purchase, not cta_click or form_error. Otherwise the key event rate grows while revenue stays flat.

Worked example: micro-events explain the key event rate

A demo form records 1,000 form_start events in a month and 180 generate_lead events. The completion rate is 180 / 1,000 = 18%. form_error fires 420 times, and field_name breaks down as 260 on work_email, 110 on phone and 50 on company_size. The phone field causes 110 / 420 = 26% of errors. If phone is optional to your sales process, removing it is a cheap test, and our guide on how many form fields a lead form needs covers that trade-off. You learn this only because a custom event and a registered parameter sit next to the key event.

How do you test GA4 event tracking with DebugView and Tag Assistant?

Google's "Monitor events in DebugView" page describes three ways to send debug traffic:

  • Tag Assistant / GTM Preview: click Preview in GTM and enter your URL. Tag Assistant shows which tags fired for each data layer message, and the traffic appears in DebugView automatically.
  • gtag.js: add debug_mode: true to the config command (or to a single event). To switch it off, remove the parameter; setting it to false does not disable it.
  • GTM without Preview: add a debug_mode parameter set to true on the Google tag or on a single GA4 Event tag.

Then open Admin, Data display, DebugView, trigger the action and check:

  1. The event appears once, not twice.
  2. The name matches the tracking plan exactly, including case.
  3. Every parameter is present with a sensible value, and none are "undefined" or empty.
  4. Key events show the key event marker.
  5. No email address, name or phone number appears anywhere in the payload.

Standard reports can take a day or longer to show new events, so judge the setup from DebugView and Realtime, not from the reports on day one.

What are the most common GA4 custom event mistakes?

Sending PII in parameters

Google's "Best practices to avoid sending Personally Identifiable Information" page forbids sending data Google could use to identify a person, such as email addresses or phone numbers. Common leaks are a form value copied into a parameter, an email address in a thank-you page URL (page_location), and search terms people type into site search. Send categories (lead_type: demo), never the input itself.

High-cardinality parameters

Google's "Cardinality" help page defines a high-cardinality dimension as one with more than 500 unique values in a day. When reports exceed their row limits, the excess values are grouped into an "(other)" row. Order IDs, timestamps, full URLs with query strings and free-text fields all cause this. Register only low-cardinality parameters as dimensions, and analyse the rest in BigQuery.

Duplicate firing

Usual causes: a hard-coded gtag snippet plus a GTM tag for the same event, a UI-created event duplicating a coded one, and single-page apps pushing the event on every re-render. Marking both enhanced measurement form_submit and generate_lead as key events also counts every lead twice.

Ignoring consent mode

In the EEA and UK, tags must respect the visitor's consent choice. Under basic consent mode, Google tags do not fire until consent is given, so events from declining visitors are missing. Under advanced consent mode, tags send cookieless pings that Google uses for modelling. Both modes produce lower event counts than your backend, and that is expected. Read our GA4 consent mode v2 guide before comparing GA4 leads with CRM leads. If ad blockers and browser restrictions cause even larger gaps, server-side tagging is the next step.

Stopping at the numbers

Events show where users drop off, not what on the page caused it. EyeCaptain's free audit reviews a page from its URL on desktop and mobile and ranks findings by impact. It is not an analytics tool, so it complements GA4 rather than replacing it. Rank the resulting fixes with a CRO prioritization framework before testing them.

Illustration 3: GA4 Custom Events: Setup, Key Events and Tracking PlanEyeCaptain

Frequently asked questions

How many custom events can I create in GA4?

For web data streams, Google's event collection limits page states there is no limit on the number of distinctly named events. The practical limits are 25 parameters per event, 50 event-scoped custom dimensions per standard property, and 50 events created in the GA4 UI. Plan around the dimension quota, not the event count.

What is the difference between key events and conversions in GA4?

They describe the same thing under different names. In 2024 GA4 renamed conversions to key events, and "conversion" is now reserved for Google Ads. A key event imported into Google Ads becomes a conversion used for bidding and reporting there.

Why do my custom event parameters not show in GA4 reports?

Most likely you have not registered them as custom dimensions, or you registered them recently. Registration applies only to data collected afterwards. Also check that the parameter name in Custom definitions matches the one you send exactly, including case.

Should I use gtag.js or Google Tag Manager for GA4 custom events?

Use GTM if marketers need to add or change tracking without a code release, or if you run several tags. Use gtag.js on small sites where a developer owns tracking and wants fewer moving parts. In both cases, the site should fire the event only after the action succeeds.

Can I create a GA4 event without code?

Yes. Admin, Data display, Events, Create event builds a new event from existing ones, such as a page_view on a thank-you URL. It cannot detect interactions GA4 does not already receive, and it does not apply to historical data. Treat it as a stopgap until you can track the event in code or GTM.

How long until a new custom event appears in GA4?

It appears within seconds in DebugView and Realtime. Standard reports can take a day or longer to process new events, so verify the setup in DebugView before you decide something is broken.

Enjoyed this article?

One short email a week with practical CRO and UX tips

No spam. Unsubscribe anytime.

Find what stops your visitors from converting

EyeCaptain is an AI-powered CRO & UX audit tool that automatically scans your pages, identifies UX issues, and gives you actionable optimization suggestions to increase conversions. Try it for free, no card, no commitment.

Free Website Audit
Share this article
LinkedIn X

About the author

Founder of EyeCaptain. Writes about conversion rate optimization, UX analysis and the neuromarketing behind pages that actually sell.

More articles by Dimitris Andreadakis