Even though the Analytics module supports Google Analytics ecommerce events by default, a store may need to monitor customer activity not covered by the Analytics module. In these cases, it is still possible to use the sendAnalyticsEvent and useAnalyticsEvent functions to fire and intercept custom events. In this guide, learn how to define and send custom events.

To fire a custom event, you first need to declare an interface that describes the structure of your event object, including all its properties and types. To do that, you can:

You can use the sendAnalyticsEvent function to create a custom event interface. This function demands that the event contains two properties:

Take the following example to track when a user adds a product to their wishlist by defining the WishlistEvent:

This custom event interface allows you to capture when a user adds a product to their wishlist. It logs details like the 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 extended existing types from the Analytics module by using the generics available on the sendAnalyticsEvent function.

Take the following example where the AddToCartEvent interface is extended to also accept the couponCode property, useful to track if a customer applied a coupon code when adding an item to the cart.:

If you have multiple custom events, like adding to the cart, removing from the cart, or viewing products, you can create a unified type to manage them all and easily fire extended events:

The example above sets up a flexible way to fire various custom events. Instead of managing multiple event types separately, the purpose of the example is to handle them all through a single interface, making. 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 creating or extending an event interface, you'll need to intercept these events using the useAnalyticsEvent hook. You can do that in the following:

Also, notice 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 them with the useAnalyticsEvent hook, you can implement it in your components to fire the event when desired.