sendAnalyticsEvent

The sendAnalyticsEvent function triggers events in the browser, following the Google Analytics 4 (GA4) data model. This function is primarily used for ecommerce tracking but also supports custom events, serving as a centralized point for managing events.

sendAnalyticsEvent doesn't send events to any analytics provider. To intercept events triggered by this function, use the useAnalyticsEvent hook.

Import


_10import { sendAnalyticsEvent } from '@faststore/sdk'

Usage

In the event-related component, define a callback function that creates an event object with the desired type (for example, add_to_cart) and calls sendAnalyticsEvent, passing the event as an argument. Then, trigger the callback function in the corresponding event handler (such as onClick).

The example below shows an add_to_cart event triggered by the button component:


_23import { useCallback } from 'react'
_23import { sendAnalyticsEvent } from '@faststore/sdk'
_23
_23const MyComponent = () => {
_23  const addToCartCallback = useCallback(() => {
_23   import('@faststore/sdk').then(({ sendAnalyticsEvent }) => {
_23    /* ... */
_23
_23    const addToCartEvent = {
_23      name: 'add_to_cart',
_23      params: {
_23        items: [
_23          /* ... */
_23        ],
_23      },
_23    }
_23
_23    sendAnalyticsEvent(addToCartEvent)
_23    })
_23  }, [])
_23
_23  return <button onClick={addToCartCallback}>Add to cart</button>
_23}

Check the list of available types.

Parameters

The sendAnalyticsEvent function accepts an event object with the following properties:

Property	Type	Description	Default
`name`	`string`	The name of the event in Analytics reports.	Required
`params`	`object`	Event-specific parameters and data.	Required
`isEcommerceEvent`	`boolean`	Determines event structure. When `true`, wraps `params` in an `ecommerce` object following the GA4 ecommerce data model. When `false`, sends `params` at the top level for custom non-ecommerce events.	`true`

`isEcommerceEvent`

By default, sendAnalyticsEvent wraps event parameters in an ecommerce object to follow the Google Analytics 4 ecommerce events structure. However, for custom events that don't represent ecommerce actions, you should set isEcommerceEvent: false to send parameters at the top level, following the GA4 custom events format.

Custom events without GA4 `ecommerce` (`isEcommerceEvent: false`)


_11import { sendAnalyticsEvent } from '@faststore/sdk'
_11
_11sendAnalyticsEvent({
_11  name: 'newsletter_signup',
_11  isEcommerceEvent: false,
_11  params: {
_11    method: 'footer_form',
_11    user_type: 'new_visitor',
_11    email_preference: 'weekly'
_11  }
_11})

This sends the event as:


_10{
_10  "event": "newsletter_signup",
_10  "method": "footer_form",
_10  "user_type": "new_visitor",
_10  "email_preference": "weekly"
_10}

GA4 ecommerce event (`isEcommerceEvent: true`)

Use isEcommerceEvent: true (default) to format the event according to the GA4 ecommerce data model, wrapping all parameters inside the ecommerce object. See the following example:


_10import { sendAnalyticsEvent } from '@faststore/sdk'
_10
_10sendAnalyticsEvent({
_10  name: 'add_to_cart',
_10  params: {
_10    currency: 'USD',
_10    value: 29.99,
_10    items: [{ item_id: '12345', item_name: 'Product Name' }]
_10  }
_10})

This sends the event as:


_10{
_10  "event": "add_to_cart",
_10  "ecommerce": {
_10    "currency": "USD",
_10    "value": 29.99,
_10    "items": [{ "item_id": "12345", "item_name": "Product Name" }]
_10  }
_10}

Typed custom events

The sendAnalyticsEvent function supports generics, enabling you to extend default types or modify existing ones. This approach provides type checking and code suggestions for your custom event properties.

This typing is independent of how the event is packaged by isEcommerceEvent. You can use generics for both GA4 ecommerce events and non-ecommerce custom events.

Consider the following example of providing a custom type reference for sendAnalyticsEvent:


_13import { sendAnalyticsEvent } from '@faststore/sdk'
_13
_13interface CustomEvent {
_13  name: 'custom_event'
_13  params: {
_13    customProperty?: string
_13  }
_13}
_13
_13/**
_13 * By passing `CustomEvent` as a generic type to `sendAnalyticsEvent`, you will receive code suggestions for all properties of this type, including nested properties within `params`.
_13 */
_13sendAnalyticsEvent<CustomEvent>(/* ... */)