Even though the Analytics module natively supports Google Analytics ecommerce events, you may need to track customer activity not covered by default events. In such cases, you can trigger and intercept custom events using the sendAnalyticsEvent and useAnalyticsEvent functions. In this guide, learn how to define and send custom events.

To trigger a custom event, you must define an interface that describes the structure of your event object, including its properties and types. There are three approaches to doing this:

To create a custom event interface, use the sendAnalyticsEvent function. This function requires the event to include two properties:

In the following example, we define a custom event called WishlistEvent to track when a user adds a product to their wishlist:

This custom event interface captures when a user adds a product to their wishlist, logging details like productId, productName, and whether the user is logged in (isLoggedIn). This data can then be sent to your analytics tool to better understand customer behavior, such as which products are popular on wishlists and how engagement varies between logged-in and anonymous users.

If your event is related to an existing one, you can extend relevant types from the Analytics module. You can do this by using the TypeScript generics with the sendAnalyticsEvent function.

The following example extends the AddToCartEvent interface to include the couponCode property, which is useful for tracking if a customer applied a coupon code when adding an item to the cart:

If you have multiple custom events, such as adding/removing items from the cart or viewing products, you can define a unified type to handle them all. This approach simplifies firing multiple events from the same interface.

The example above sets up a flexible way to fire multiple custom events. Instead of managing multiple event types separately, the purpose of the example is to handle them all through a single interface. You can use this setup to track diverse customer interactions, such as adding/removing products from the cart, viewing products, or saving items to the wishlist.

After defining the event interface, you'll need to intercept these events using the useAnalyticsEvent hook. Below is an example of how to set up an event handler:

Note that to target extended properties of events, you'll also need to configure the types of your useAnalyticsEvent callback function to expect an event of such type.

Now that you have declared your event interface and intercepted it with the useAnalyticsEvent hook, you can implement it in your components to fire the event.