Guide 195 · Events · GA4 + Tag Manager
Send a custom event with gtag.js: one gtag call below the tag snippet, and the check in Realtime
A custom event in gtag.js is one gtag call with the event name and its parameters, placed below the Google tag snippet — Google's own example sends signup_newsletter with a method parameter.
After step 5, the custom event appears in Realtime within minutes, and DebugView shows the event with the parameters you sent.
Download the reference: the gtag custom event reference (JSON) (1471 bytes, MD5 027d401e730c82b2ed995c466a2a4ce1). It holds the report or event definition and the worked example with the recomputed figures shown on this page.
What you need
- A GA4 account and property, a web data stream, and the Google tag on the site. The guide assumes all three are already in place.
- Access to the site source code — you add the call in the page JavaScript, below the Google tag snippet.
- The Editor role or above on the GA4 account, so you can register the custom parameters as custom dimensions afterwards.
The trace
- Learn the one call. The Google tag API has one function,
gtag(). To send an event you use the event command, the event name, and optional parameters:gtag('event', '<event_name>', { <event_parameters> });. That is the whole call — the event command tells Google you are sending an event, the name tells it which event, and the parameters carry the extra information. - Place the call below the Google tag snippet. Add the
gtag()function to the JavaScript on the page, anywhere below the Google tag snippet. Google will not process data from events that you place above the snippet. Google's own sample page sends a recommended event and a custom event from the same script block, both below the snippet. - Send a recommended event with its prescribed parameters first. Google's example sends
screen_viewwithapp_nameandscreen_name, andloginwithmethodset to Email. A recommended event uses the standard name and the predefined parameters, which is what unlocks the prebuilt reporting for it. Onegtag('event', ...)call sends one event — there is no call that sends several different events at once. - Send a custom event the same way, with your own name. Google's example sends a custom event called
signup_newsletterwith amethodparameter set to web, and a custom event calledtutorial_completewith atutorial_nameparameter. Pick the custom event when no recommended event fits the action. The worked example below runs the tutorial pair and the login method split, so the counts can be read as rates. - Check it in Realtime and DebugView. You can see your events and their parameters in the Realtime and DebugView reports, which show events as they are triggered. DebugView needs some extra configuration before you can use it. Standard reports take longer — the same-day check belongs in Realtime, not in a standard report.
- Register the custom parameters to see them in reports. Sending a custom parameter in code is only the first step. To display and analyze the values of custom parameters in standard reports and explorations, you must register them as custom dimensions or metrics in the GA4 interface. After you register one, it can take up to 48 hours for the data to become available in reports.
Dead ends
DEAD END — PLACING THE CALL ABOVE THE TAG SNIPPET. Google will not process data from events placed above the Google tag snippet. The call looks right, the page loads, and nothing arrives. The fix is placement, not the event name: move the call below the snippet.
DEAD END — SENDING A CUSTOM EVENT AND EXPECTING A PREBUILT REPORT. A custom event is one you define because no recommended event fits, and it is accessible using custom reports only. If you want the prebuilt reporting panel, use the recommended event with its prescribed parameters instead of inventing a name for the same action.
DEAD END — READING A CUSTOM PARAMETER IN A STANDARD REPORT BEFORE REGISTERING IT. The parameter arrives with the event either way, but GA4 will not show it as a dimension until you register it as a custom dimension. An empty column next to a working event is a registration gap, not a collection gap.
End state
The gtag route is the code route: one call per event, placed below the snippet, checked in Realtime. The worked example below turns the tutorial and login counts into rates.
Worked example — stated inputs, recomputed results. A tutorial runs two events, and a login form sends one event with a method. The rates below are recomputed from the counts.
| Event | Count | Rate |
|---|---|---|
tutorial_begin | 240 | — |
tutorial_complete | 96 | 40.0% completion |
login, method Email | 74 of 118 | 62.7% by Email |
Completion is 96 ÷ 240 = 40.0%. The Email share of logins is 74 ÷ 118 = 62.7%.
Sources
- Google Analytics — Set up events — the gtag event call, placement below the snippet, the screen_view, signup_newsletter, login, share and tutorial_complete examples, and the Realtime and DebugView check
- Google Analytics — Recommended events — that recommended events have standard names and predefined parameters, that custom events are the ones you define yourself, and that a custom event is accessible using custom reports
Checked 11 November 2026. The click paths above are the ones in Google's help and developer pages, opened in full on 11 November 2026. No step in this guide was run inside a live Analytics property, because that needs a Google sign-in and this site does not sign in as anyone. The worked-example figures on this page were recomputed in Python with decimal arithmetic, and the downloadable JSON file carries the same recomputed figures. Google moves menu items without warning; if a path on this page no longer matches, the linked help page is the current map.