A user sometimes performs an action you want to analyze in your reports that isn't one of the automatically collected or recommended events. In these cases, it may make sense to implement a custom event.
A custom event is an event that you define so you can collect information about an interaction that's important to your business.
For example, while Google Analytics records when a user views a page, you may want to know when a user makes a donation, interacts with a new feature, lands on a confirmation page, or renames a file. In these cases, you likely want to implement a custom event.
Watch a video about custom events
Before you create a custom event
Before you create a custom event, make sure the event you want to create isn't already collected through an automatically collected event or recommended as a recommended event. It's always better to use an existing event because these events automatically populate dimensions and metrics that are used in your reports.
How to implement a custom event
You can implement a custom event in a few different ways, depending on how you set up your website or app measurement. These includes:
The specific implementation details differ depending on how you set up your website or app measurement. Refer to the developer documentation (liked above) for more details on how to implement a custom event.
The anatomy of a custom event
A custom event consists of the following parts:
- The custom event name
- The custom event parameters associated with the custom event
Event name
The name of a custom event is whatever name you choose for the event. The name should describe what you intend to measure with the event. For example, if you're measuring donations, the name might be "donate."
Before you name a custom event, make sure the name adheres to the event naming rules (e.g., the name is case sensitive, cannot be a reserved name, and starts with a letter) and event naming limits (i.e., the name must be fewer than 40 characters in length) to ensure that Google Analytics collects and processes the event.
When someone triggers the custom event on your website or app, the event name is used to count how many times a user performed the action. For example, if someone makes a donation, then the count of the donate event would increase by 1. Any additional information about the donation should be captured as custom event parameters.
Event parameters
The event parameters of a custom event provide more information about the action that took place. For example, you could measure whether the action was successful, when the event occurred, or choices users made during the interaction.
A parameter consists of key-value pairs. Each pair includes these parts:
- The parameter name, which describes the information you're collecting
- The parameter value, which is the value associated with the parameter in that interaction
The parameter name is the same name used across sessions, while the parameter value should get updated depending on what the user does in the session. For example, if one user makes a donation of $1.00, then the 'value' parameter would be '1.00', while if another user makes a donation of $2.00, then the 'value' parameter would be '2.00'. This allows you to consistently measure the same information across sessions.
Custom dimensions and metrics
To access the different values assigned to an event parameter in your reports, you should create a custom dimension or metric. A custom dimension or metric lets you see the information you collected from an event parameter. For example, if you set up a 'value' event parameter, you could create a custom metric called 'Value' that allows you to see each value assigned to the event parameter. Learn more about custom dimensions and metrics.
Cardinality and system limits
While you set up a custom event parameter, be mindful of the number of possible values that can be assigned to the parameter.
Each parameter can have a number of values assigned to it. For example, a 'mobile' custom event parameter might have two potential values – 'true' or 'false'. Other parameters might have any number of values assigned, such as 'page_location', which could have a different value for every URL on your website.
When you create a custom dimension to see categorical information like page_location, the number of possible values matters. Dimensions with more than 500 possible values are considered high-cardinality dimensions. Reports and explorations that contain high-cardinality dimensions may be affected by Google Analytics system limits, which can lead to values getting rolled up in an (other) row or data sampling may get triggered.
Additionally, review the number of custom dimensions and metrics you can create before creating custom event parameters. If you send more event parameters than these limits, you will need to choose which of these event parameters you want to use as custom dimensions and metrics.
Event collection limits
There's no limit on the number of custom events you can create for a web data stream (i.e., a website). However, you can collect up to 500 distinct events per mobile app user per day. For example, you might see 700 distinct events if you have two different users on different app instances who each trigger different events.
The automatically collected and enhanced measurement events don't count towards these limits.
Review the other event collection limits before creating your own events.
Key events
Any custom event can be marked as a key event. For example, if donations are important to the success of your business, you might mark the custom event 'donate' as a key event.
Sometimes, the action you want to measure is partially captured through an existing event, but you want to narrow the scope of the event to measure an action that's important to your business. For example, Analytics already measures pageviews automatically, but you may want a separate custom event for when someone views a confirmation page.
Instead of creating a custom event in these cases, you could create a copy of the event or modify the event directly, from within Google Analytics. Then, you could mark the event as a key event. This allows you to create events quickly without needing to update your website code.
However, make sure to communicate these changes with the person who makes changes to your website code if that isn't you. Otherwise, you may overcount the interaction if they too create a custom event for that interaction.
See the events in your reports
After you implement a custom event and Google Analytics collects the event, you can use the Events report in the Reports section to see how many times the event was collected and other data about the event in the specified date range.
You can also select an event name to open a more detailed report about that event, including details about the parameters, demographics about the users who triggered the event, and how many users triggered each event (and the associated parameters) in realtime.