Tracking custom events
Learn how to send custom analytics events from your application.Custom Events are available on Pro and Enterprise plans
Vercel Web Analytics allows you to track custom events in your application using the track()
function.
This is useful for tracking user interactions, such as button clicks, form submissions, or purchases.
Make sure you have @vercel/analytics
version 1.1.0 or later
installed.
To track an event:
-
Make sure you have
@vercel/analytics
version 1.1.0 or later installed. -
Import
{ track }
from@vercel/analytics
. -
In most cases you will want to track an event when a user performs an action, such as clicking a button or submitting a form, so you should use this on the button handler.
-
Call
track
and pass in a string representing the event name as the first argument. You can also pass custom data as the second argument:component.tsimport { track } from '@vercel/analytics'; // Call this function when a user clicks a button or performs an action you want to track track('Signup');
For example, if you have a button that says Sign Up, you can track an event when the user clicks the button:
import { track } from '@vercel/analytics';
function SignupButton() {
return (
<button
onClick={() => {
track('Signup');
// ... other logic
}}
>
Sign Up
</button>
);
}
You can also pass custom data along with an event. To do so, pass an object
with key-value pairs as the second argument to track()
:
track('Signup', { location: 'footer' });
track('Purchase', { productName: 'Shoes', price: 49.99 });
In scenarios such as when a user signs up or makes a purchase, it's more useful to track an event on the server-side. For this, you can use the track
function on API routes or server actions.
To set up server-side events:
- Make sure you have
@vercel/analytics
version 1.1.0 or later installed. - Import
{ track }
from@vercel/analytics/server
. - Use the
track
function in your API routes or server actions. - Pass in a string representing the event name as the first argument to the
track
function. You can also pass custom data as the second argument.
For example, if you want to track a purchase event:
'use server';
import { track } from '@vercel/analytics/server';
export async function purchase() {
await track('Item purchased', {
quantity: 1,
});
}
The following limitations apply to custom data:
- The number of custom data properties you can pass is limited based on your plan.
- Nested objects are not supported.
- Allowed values are
strings
,numbers
,booleans
, andnull
. - You cannot set event name, key, or values to longer than 255 characters each.
Once you have tracked an event, you can view and filter for it in the dashboard. To view your events:
- Go to your dashboard, select your project, and click the Analytics tab.
- From the Web Analytics page, scroll to the Events panel.
- The events panel displays a list of all the event names that you have created in your project. Select the event name to drill down into the event data.
- The event details page displays a list, organized by custom data properties, of all the events that have been tracked.
Was this helpful?