Sending custom events

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, you'll learn how to define and send custom events.

For a practical example of sending custom events, see the Implementing custom newsletter analytics events guide.

Instructions

Step 1 - Declaring an interface for your custom event

To trigger a custom event, you must define an interface that describes the structure of your event object, including its properties and types. You can do this in three ways:

Creating a new event interface
Extending existing types from the Analytics module
Overriding multiple types

Creating a new event interface

To create a custom event interface, use the sendAnalyticsEvent function.

In the following example, we define a custom event called WishlistEvent to track when a user adds a product to their wishlist. Since this is not a standard ecommerce event, we set isEcommerceEvent: false:


_23import { sendAnalyticsEvent } from '@faststore/sdk'
_23
_23interface WishlistEvent {
_23    name: 'wishlist_event'
_23    isEcommerceEvent: false
_23    params: {
_23        productId: string
_23        productName: string
_23        userId: string
_23        isLoggedIn: boolean
_23    }
_23}
_23
_23sendAnalyticsEvent<WishlistEvent>({
_23    name: 'wishlist_event',
_23    isEcommerceEvent: false,
_23    params: {
_23        productId: '12345',
_23        productName: 'Example Product',
_23        userId: 'user-abc',
_23        isLoggedIn: true
_23    }
_23})

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). By setting isEcommerceEvent: false, the parameters are sent at the top level of the event payload, following the Google Analytics 4 format for custom events.

Extending existing types from the Analytics module

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:


_10import type { AddToCartEvent } from '@faststore/sdk'
_10import { sendAnalyticsEvent } from '@faststore/sdk'
_10
_10interface AddToCartExtended extends AddToCartEvent {
_10    couponCode: string
_10}
_10
_10/* ... */
_10
_10sendAnalyticsEvent<AddToCartExtended>({ name, params, couponCode })

Overriding multiple types

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.


_18/* types.ts */
_18import { sendAnalyticsEvent } from '@faststore/sdk'
_18
_18type AddToCartExtended = /* ... */
_18type RemoveFromCartExtended = /* ... */
_18type ViewItemExtended = /* ... */
_18type SelectItemExtended = /* ... */
_18
_18type ExtendedEvents =
_18| AddToCartExtended
_18| RemoveFromCartExtended
_18| ViewItemExtended
_18| SelectItemExtended
_18
_18type SendExtendedAnalyticsEvent = (event: ExtendedEvents) => void
_18
_18export const sendExtendedAnalyticsEvent: SendExtendedAnalyticsEvent = (event) =>
_18sendAnalyticsEvent<ExtendedEvents>(event)


_10/* MyComponent.tsx */
_10import { sendExtendedAnalyticsEvent } from './types'
_10
_10/* ... */
_10
_10sendExtendedAnalyticsEvent({ /* Extended event object */})

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.

Step 2 - Intercepting custom events

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:


_12import { useAnalyticsEvent } from '@faststore/sdk'
_12
_12import type { ArbitraryEvent } from './types'
_12
_12export const AnalyticsHandler = () => {
_12useAnalyticsEvent((event: ArbitraryEvent) => {
_12})
_12
_12/* ... */
_12
_12return null
_12}

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 that type.


_14import { useAnalyticsEvent } from '@faststore/sdk'
_14
_14import type { ExtendedEvents } from './types'
_14
_14export const AnalyticsHandler = () => {
_14
_14useAnalyticsEvent((event: ExtendedEvents) => {
_14    /* ... */
_14})
_14
_14/* ... */
_14
_14return null
_14}

By typing the callback function with the extended types, you can reference properties not natively provided by the Analytics module.

Step 3 - Firing custom events

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


_18import { useCallback } from 'react'
_18import { sendAnalyticsEvent } from '@faststore/sdk'
_18
_18const MyComponent = () => {
_18const handleCustomEvent = useCallback(() => {
_18    sendAnalyticsEvent({
_18    name: 'custom_action',
_18    isEcommerceEvent: false,
_18    params: {
_18        action_type: 'button_click',
_18        component_name: 'MyComponent',
_18        timestamp: new Date().toISOString()
_18    }
_18    })
_18}, [])
_18
_18return <button onClick={handleCustomEvent}>Trigger Custom Event</button>
_18}

Use isEcommerceEvent: false for custom events that track user interactions, feature usage, or other non-commerce activities. Reserve the default isEcommerceEvent: true (or omit it) for events related to the shopping funnel (add to cart, purchase, etc.).