GA4 Event Builder

Every chart in an analytics report began as a small message that a page sent when something happened. Someone chose the words in that message. Usually they chose them in a hurry.

A name and a handful of labelled values

In Google Analytics 4 the unit of measurement is the event. The developer guide puts it plainly: events let you measure interactions on a site or an app, such as loading a page, clicking a link or completing a purchase, and the reports are built from that data. The same guide sorts events into four kinds. Some are collected automatically once the tag is installed. Some come from a feature called enhanced measurement. Some are recommended, with names and parameters the platform already understands. The rest are custom, which means you made them up.

Whatever its kind, an event has the same shape: a name, and optionally a set of parameters, each of which is a name with a value. The tag’s programming interface reflects that directly. Its event command takes three things, the word event, the name of the event and an object of parameter and value pairs, and the guide notes that recommended and custom events are sent the same way. There is a second route for sites that run a tag manager: the page pushes an object onto a list called the data layer, with the event name under a key called event, and the container decides what to do with it.

That is the whole model. It is simple enough to learn in ten minutes, and that simplicity hides where the work is. The interface will accept almost any text as a name. It does not know what your team agreed last spring. It cannot tell a considered name from a typo.

Recommended names first, custom names with care

The reference for recommended events is the best place to start, because a name taken from it means the same thing to the platform as it does to you. As read on 11 October 2026 the page lists 35 events in four groups: events for all properties, online sales, games and lead generation. Each has a table giving every parameter’s name, its type and whether it is required. The guide describes these as standardised events that unlock reporting the platform has already built, while custom events are those you define because nothing else fits, and they surface through reports you assemble yourself.

So the first question about any new event is whether it already exists. A sign-up is sign_up. A site search is search, with a search_term that the table marks as required. Borrowing the name costs nothing and saves an argument.

Custom names are where discipline matters, because the help centre is explicit that names are case sensitive. An event called sign_up and one called signUp are two different events with two different counts, and neither total is the number of sign-ups. A third spelling with a hyphen is worse than a duplicate, because the published rule allows only letters, digits and underscores. Three developers, three reasonable instincts, one unusable report.

This is the argument for treating names as a shared vocabulary instead of a detail of implementation. A report groups rows by the exact text of the name. It will never merge two spellings for you, and no later clean-up can recover an event that was dropped at the door.

The limits that drop data without telling you

The limits are published, and they are short. The developer documentation for the server-side protocol states that event names must be 40 characters or fewer, may contain only alphanumeric characters and underscores, and must start with an alphabetic character. Parameter names follow the same rule. Parameter values must be 100 characters or fewer on a standard property and 500 on a 360 property. An event can carry a maximum of 25 parameters. User properties, the labels that describe segments of your visitors instead of single actions, get 24 characters for a name and 36 for a value.

Those sentences are written about the server-side protocol, but the help centre lists the same numbers for events collected by a tag, and adds the detail that matters most: what exceeds a limit is not logged. The twenty-sixth parameter is not rejected with a message. It simply is not there, and the reference for the event command describes no reply that would tell the page so.

Even the word “characters” needs care. The developer page does not define it. The help centre says that the limits are the same for single-width and double-width scripts and that the encoded URL length is what is counted, which suggests that text outside plain ASCII uses up its allowance faster: an accented e becomes six characters when percent-encoded, and a single emoji becomes twelve. A cautious team counts the encoded form as well as the visible one.

Some names are taken. The protocol reference lists reserved event names, among them session_start, first_visit and error, and forbids parameter names that begin with an underscore or with firebase_, ga_ or google_. The page says only that they cannot be used, which is reason enough.

The documentation also disagrees with itself in places, and it is better to say so than to pick a side. One page allows up to 27 custom parameters on an item in a commerce event; another gives a maximum of 10. One page says “alphanumeric”; another says letters from other alphabets are welcome. Where two official pages differ, the honest reading is that the stricter number is safe and the looser one is a risk. And every figure here is guidance read on one date. Limits can change, so check the current documentation before relying on any of them.

A worked example

Take a shop that sells glass jars. An order is paid, and the page should say so. The reference for the purchase event marks transaction_id as required, asks for currency and value together, and requires an items array in which each item carries an item_id or an item_name. It also says how to compute the value: the sum of price times quantity across the items, without shipping or tax.

The order holds three large jars at 12.5 each and one scoop at 5, so the value is 42.5. The amounts are plain illustrative numbers, and the currency is written XTS, the ISO 4217 code reserved for testing, so nobody mistakes the snippet for real money. With transaction_id set to T-10482 and a coupon of AUTUMN, the event has five parameters against the limit of 25, since the items array counts as one, and a name of 8 characters against the limit of 40. Nothing is flagged.

Now break it, one change at a time. Capitalise the name to Purchase and it is no longer the recommended event but a custom one that merely resembles it. Delete the currency and the event contradicts a sentence in its own reference: currency is required if you set value. Rename coupon to ga_coupon and the parameter begins with a reserved prefix. Each of these would have shipped without complaint.

There is one more way for the snippet to fail, and it has nothing to do with the platform. A value is text that somebody else typed, and it has to survive being written into JavaScript. Quotes and backslashes need escaping. So do line ends, and the language specification counts four of them, including two Unicode separators that most editors never show.

If the code sits inside a script element there is a further trap. The HTML Standard describes some strange restrictions on a script’s text and says the easiest and safest way to avoid them is always to escape three sequences, <!--, <script and </script, by writing their less-than sign as an escape. A product called “Jars ” would otherwise close the script element in the middle of a string.

Consent, personal data and writing things down

Correct code is not the same as permitted code. In the European Union, Article 5(3) of the directive on privacy and electronic communications allows storing information on a person’s device, or reading information already stored there, only when that person has consented after being given clear information, unless the storage is strictly necessary for a service they asked for. The General Data Protection Regulation defines consent as freely given, specific, informed and unambiguous. Other jurisdictions have their own rules. None of this is legal advice, but the practical point is plain: an event snippet should run only where your consent logic says it may.

Parameters are also an easy place to leak personal data by accident. The platform’s help centre says its policies forbid sending anything it could recognise as personally identifiable information, and gives email addresses and personal mobile numbers as examples. The regulation’s definition is wider still: any information relating to an identifiable person. A parameter called user_email is a warning sign whatever it contains.

The remedy for most of the above is unglamorous. Keep a dictionary: one row per event, with its exact name, what it means in a sentence, its parameters and their types, where it fires, who owns it and whether it is planned, live or retired. A spreadsheet will do. If it travels as a CSV file, remember that a cell beginning with an equals sign, a plus, a minus or an at sign can be run as a formula by the program that opens it, which is why careful exporters put a quote in front.

A dictionary makes duplicates visible before they reach production. It gives a new developer somewhere to look. It turns “what did we call that?” from a search through old code into a lookup.

No builder or checker can do the last part of the job. It cannot confirm that an event arrived, because that needs the platform’s own debugging view. It cannot know what a variable will hold when a real visitor triggers it. It cannot see rules that were never published, or tomorrow’s revision of the ones that were.

What it can do is make the cheap mistakes impossible to miss. Names are decisions. Write them down once, check them against the published rules, and send them the same way every time.