The four kinds of events
Google groups events by where the name comes from, and the grouping matters because it decides how much work each one needs and how reliably reports understand it.
| Kind | Who names it | Examples | What you do |
|---|---|---|---|
| Automatically collected | The tag, with no configuration | first_visit, session_start, user_engagement on the web; first_open, screen_view in apps | Nothing; they arrive once the tag is installed |
| Enhanced measurement | The tag, when the option is switched on in the stream | page_view on history changes, scroll, click (outbound), view_search_results, file_download, form_start, form_submit, video_start, video_progress, video_complete | Switch each option on or off and configure site search parameters |
| Recommended | Google, as a published list with prescribed parameters | login, sign_up, generate_lead, search, share, view_item, add_to_cart, begin_checkout, purchase, refund | Implement them yourself, using the documented names and parameters |
| Custom | You | quote_requested, plan_selected, calculator_used | Name, implement and register them yourself |
Automatically collected and enhanced measurement events cost nothing and describe the mechanics of a
visit. They rarely describe the business. Recommended events are the ones Google has pre-wired into
reports: the e-commerce reports read view_item, add_to_cart and purchase with their items arrays;
the generate-lead and sign-up events are offered as key event candidates; the Google Ads import
recognises them. Custom events fill the gaps, and the only rule is that there should be few of them and
each should be impossible to confuse with another. The list of events a property sends, with their
parameters and the pages or actions that fire them, is the tracking plan,
and this guide assumes one is being written as the schema is designed.
Names are case-sensitive, so Purchase and purchase are two events in every report. Google reserves
some prefixes for its own events and documents the characters a name may contain; the practical convention
is lower-case words joined with underscores, which is how every automatic and recommended event is already
written.
Parameters: event-scoped, user properties, item-scoped
A parameterA named value sent with an analytics event that describes it, such as a page location, form name or item price. is a name and a value attached to an event. Every event carries a set of automatic parameters
— the page location, referrer and title, the language, the screen resolution — and recommended events
carry the parameters Google documents for them, such as value, currency and method. Anything else
is a custom parameter. All of these are event-scoped: they describe the event they travel with and
nothing else. An event-scoped parameter is the right place for things that change from one event to the
next: which form was submitted, which plan was selected, which filter was applied.
User properties are different. They describe the person rather than the action, are set once and then attached to every subsequent event from that user until changed, and are reported at user scope. Customer type, subscription tier, logged-in status and signup cohort belong here. Sending them as event parameters instead means every report that wants them has to find them on the right event, and user-level questions ("how many enterprise customers visited?") become unanswerable. Setting a user property on every page view is a common workaround that works badly.
Item-scoped parameters live inside the items array that the e-commerce events carry. Each item has
documented fields — identifier, name, brand, category, variant, price, quantity — and can carry custom
item parameters for anything else about the product. They are reported through the item dimensions, which
is why a product-level question has to be asked of an e-commerce event and not of a page view. The
e-commerce tracking tutorial covers the array in detail; the point
here is that the scope of a parameter decides which reports can show it, a distinction the
reports and dimensions guide returns to from the reporting side.
Custom definitions and why unregistered parameters do not report
The single most common question about GA4 events is why a parameter that is visibly arriving in DebugView is missing from every report. The answer is that collection and reporting are separate. GA4 collects every parameter the tag sends and stores it with the event, and the BigQuery export contains all of it. The reporting layer, however, only builds dimensions and metrics for parameters that have been registered as custom definitions: a custom dimensionA GA4 reporting field created by registering an event, user or item parameter so it appears in reports and explorations. for a text value at event, user or item scope, or a custom metric for a numeric value at event scope with a unit such as currency or time.
Registration is done in Admin under Custom definitions by giving a display name, a scope and the exact parameter name. It is not retroactive for the reporting interface: data collected before the definition existed stays invisible there, and the first new data takes a short while to appear. Register parameters as part of the schema, before the event ships, not after someone notices a gap. Two cautions. A custom dimension that holds a different value on almost every event — a timestamp, a session identifier, a full URL with query stringA key and value appended to a URL after a question mark, such as a filter, sort order, session or tracking tag, that may or may not change the page. — is high-cardinalityThe number of distinct values a dimension or field holds; high-cardinality dimensions, such as page paths with IDs, can exceed report row limits., and standard reports will collapse its long tail into an "(other)" row. And a parameter that could identify a person must not be sent at all, let alone registered; Google's terms forbid it and no report needs it. The guide to keeping personal data out of analytics lists the routes by which such values arrive without anyone choosing to send them, from form fields in page addresses to site search terms, and the sweep that finds them.
The documented limit on custom definitions per property is generous for most sites and tight for a site that registers everything out of habit. Register what a report will use; leave the rest in the export.
Designing an event schema
A schema is the set of events, their parameters, the user properties and the custom definitions, designed together. Start from the questions in the measurement plan and the KPIA metric tied directly to an objective. each report must move, not from the pages of the site. For each question, ask which action answers it, whether a recommended event already names that action, which parameters a report would need to split the answer, and what scope those parameters have. Then apply a few rules.
Prefer one event with a parameter to many events that differ by a word. A form_submit with a
form_name parameter supports every form on the site and a single report splits it; contact_form_submit,
quote_form_submit and callback_form_submit are three events that each need their own key event, their
own report and their own registration. The exception is when the actions mean different things to the
business, in which case they should be different events — a quote request and a newsletter signup are not
variants of each other. Keep the vocabulary small and the parameter values controlled, which means the
developer sends quote rather than whatever the page heading said. Write the contract down as a data
layer specification, which is what the data layer guide covers, so that the
container built in Tag Manager (GTMTag management system.) reads stable keys rather than scraping the page.
A B2B software company's event schema
A B2B software company with a free trial and a sales-assisted plan designs its schema from four questions: how many trials start, how many become paid, which content precedes a trial, and which plan people choose. The schema has three custom events and reuses two recommended ones.
| Event | Parameters | Custom definitions registered |
|---|---|---|
sign_up (recommended) | method, plan_interest | plan_interest (event scope) |
generate_lead (recommended) | form_name, lead_type | form_name, lead_type (event scope) |
trial_started | plan, seats | plan (event scope), seats (custom metric) |
plan_selected | plan, billing_period | billing_period (event scope) |
content_milestone | content_group, milestone | content_group, milestone (event scope) |
User properties: customer_tier (free, trial, paid) and signup_cohort (year and month), both registered
at user scope. The developer contract is a single data layer push per event:
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: "trial_started",
plan: "team",
seats: 5,
user_properties: { customer_tier: "trial", signup_cohort: "2026-10" }
});
In the first quarter the property records 1,840 trial starts, of which 312 reach plan_selected, a
trial-to-plan rate of about 17%; the content_group dimension shows that trials preceded by a
comparison page convert at nearly twice the rate of those preceded by a blog post, which reshapes the
content plan.
Once the schema exists, every new request — "can we track clicks on the pricing toggle?" — is tested against it: which question does it answer, which existing event or parameter covers it, and whether it earns a custom definition. Most requests turn out to be a parameter on an existing event.
Limits and quotas to design around
GA4 documents limits on almost every part of the model, and the published numbers are the only ones to rely on; the help centre linked in the sources holds the current list, and this guide deliberately does not restate the figures because Google revises them. The ones that shape schema design are: the length of an event name and of a parameter name and value, which punishes verbose naming; the number of parameters a single event may carry, which punishes events that try to describe everything at once; the number of custom dimensions and metrics a property may register at each scope, which punishes registering by habit; the number of user properties; the number of distinct event names an app instance may send, which punishes generating names dynamically; and the number of key events and audiences a property may hold. App properties have additional collection limits per user and per day.
Design for them by keeping names short and consistent, by preferring parameter values to event-name variants, by registering only what reports use, and by never building a name or a parameter from free text. A schema that respects the limits with room to spare also tends to be the one people can remember. Where a question needs more than the limits allow — hundreds of attributes per event, or every URL as a dimension — the answer is the BigQuery export, where the raw parameters are all present and the interface limits do not apply.
Modifying and creating events in the interface vs in the tag
Admin offers two rules that act on incoming events before they are stored. Modify event changes an
event's name or parameters when conditions match — renaming a mis-sent event, rewriting a parameter value,
adding a parameter. Create event makes a new event from an existing one when conditions match, optionally
copying the source parameters and adding others; the classic use is deriving generate_lead from a
page_view whose location matches a thank-you page, so that a lead can be marked as a key event without a
developer release. Both apply to data from the moment the rule is saved, never retroactively, both count
against a documented limit per property, and both are evaluated in a documented order that is worth
checking before chaining rules.
The question is when to use them rather than changing the tag. Interface rules are right for a quick correction while the tag fix is scheduled, for a derived event the tag has no reason to know about, and for properties where nobody controls the tag. They are wrong as a permanent substitute for a clean implementation, for three reasons. The original event still exists after a create rule, so marking both as key events double-counts. The rules live in a place developers and the next analyst will not look, so a property that depends on several of them becomes impossible to reason about from the tag alone. And rules are per property, so a second property for the same site has to repeat them. Keep the tag and the data layer as the source of truth, document every interface rule in the tracking plan with its reason, and remove rules once the tag has been corrected. The conversion rate (CVRShare of visits or clicks that convert.) a report shows is only as honest as the chain of events behind it, and a chain that runs through undocumented rewrites is not one anyone can defend.
Common mistakes
- A different event for every button. Dozens of custom events where one event with a parameter would do, each needing its own registration and report.
- Sending parameters nobody registers. The data arrives, the report stays empty, and the gap is found months later when the question is asked.
- Registering everything. Custom definition slots used on parameters no report reads, until a real need finds the limit reached.
- Recommended names for the wrong actions. A
purchaseon a basket view or aloginon page load corrupts every report and import that trusts the name. - Mixed case and spelling drift.
Form_Submit,form_submitandformSubmitarriving from different pages, each reported separately. - User attributes sent as event parameters. Customer tier on every page view instead of a user property, so user-scoped questions cannot be answered.
- High-cardinality dimensions. Full URLs, timestamps and identifiers registered as dimensions, producing reports that are mostly "(other)".
- Interface rules as the implementation. A property whose event list only makes sense with the modify and create rules open in another tab.
The GA4 hub places this guide in the wider model, and the key events guide picks up where the schema ends: deciding which of these events count.
