EDU-15723: isEcommerceEvent property
#2309
Conversation
Navigation Preview LinkNo changes detected in the navigation.json file |
Grammar review summaryReview for
|
Preview LinksOpen this URL to set up the portal with this branch changes. You can now access the edited pages with the following URLs:
|
Grammar review summaryReview for
|
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Grammar review summaryReview for
|
Documentation feedback for docs/faststore/docs/sdk/analytics/sending-custom-events.mdxGeneral FeedbackThe guide provides a good overview of how to send custom events in FastStore using Actionable Feedback
Suggested Revision---
title: "Sending custom events"
slug: "sending-custom-events"
excerpt: "Learn how to define and send custom events in FastStore using the sendAnalyticsEvent and useAnalyticsEvent functions."
createdAt: "2024-01-01T00:00:00Z"
---
Even though the [Analytics](https://developers.vtex.com/docs/guides/faststore/analytics-overview) module natively supports [Google Analytics ecommerce events](https://support.google.com/analytics/answer/14434488?hl=en), 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`](https://developers.vtex.com/docs/guides/faststore/analytics-send-analytics-event) and [`useAnalyticsEvent`](https://developers.vtex.com/docs/guides/faststore/analytics-use-analytics-event) functions. In this guide, you will learn how to define and send custom events to track customer activity beyond the default events provided by the Analytics module.
> ℹ️ For a practical example of sending custom events, see the [Implementing custom newsletter analytics events](https://developers.vtex.com/docs/guides/faststore/analytics-implementing-custom-newsletter-analytics-events) guide.
## Before you begin
Before you start, make sure you have:
* A FastStore project set up.
* Familiarity with TypeScript and React.
* The `@faststore/sdk` package installed.
## Instructions
### Step 1 - Declare 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. There are three approaches to doing this:
- [Creating a new event interface](#creating-a-new-event-interface)
- [Extending existing types from the Analytics Module](#extending-existing-types-from-the-analytics-module)
- [Overriding Multiple Types](#overriding-multiple-types)
#### Creating a new event interface
To create a custom event interface, use the `sendAnalyticsEvent` function. This function requires the event to include the following properties:
| Property name | Type | Description | Default |
| ------------------- |-------- |---------------- |---------|
| `name` | `string` | The name of the event that appears in Analytics reports. The `name` does not need to follow any event name conventions related to natively supported events. | Required |
| `params` | `any` | Any type and value for your custom event. | Required |
| `isEcommerceEvent` | `boolean` | 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](https://support.google.com/analytics/answer/14240153?hl=en). | `true` |
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`:
```ts
import { sendAnalyticsEvent } from '@faststore/sdk'
interface WishlistEvent {
name: 'wishlist_event'
isEcommerceEvent: false
params: {
productId: string
productName: string
userId: string
isLoggedIn: boolean
}
}
sendAnalyticsEvent<WishlistEvent>({
name: 'wishlist_event',
isEcommerceEvent: false,
params: {
productId: '12345',
productName: 'Example Product',
userId: 'user-abc',
isLoggedIn: true
}
})
```
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](https://support.google.com/analytics/answer/14240153?hl=en).
#### 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's generics](https://www.typescriptlang.org/docs/handbook/2/generics.html) with the [`sendAnalyticsEvent`](https://developers.vtex.com/docs/guides/faststore/analytics-send-analytics-event) 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:
```ts
import type { AddToCartEvent } from '@faststore/sdk'
import { sendAnalyticsEvent } from '@faststore/sdk'
interface AddToCartExtended extends AddToCartEvent {
couponCode: string
}
/* ... */
sendAnalyticsEvent<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.
```ts
/* types.ts */
import { sendAnalyticsEvent } from '@faststore/sdk'
type AddToCartExtended = /* ... */
type RemoveFromCartExtended = /* ... */
type ViewItemExtended = /* ... */
type SelectItemExtended = /* ... */
type ExtendedEvents =
| AddToCartExtended
| RemoveFromCartExtended
| ViewItemExtended
| SelectItemExtended
type SendExtendedAnalyticsEvent = (event: ExtendedEvents) => void
export const sendExtendedAnalyticsEvent: SendExtendedAnalyticsEvent = (event) =>
sendAnalyticsEvent<ExtendedEvents>(event)
```
```ts
/* MyComponent.tsx */
import { sendExtendedAnalyticsEvent } from './types'
/* ... */
sendExtendedAnalyticsEvent({ /* 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 - Intercept 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:
```ts
import { useAnalyticsEvent } from '@faststore/sdk'
import type { ArbitraryEvent } from './types'
export const AnalyticsHandler = () => {
useAnalyticsEvent((event: ArbitraryEvent) => {
})
/* ... */
return null
}
```
Note that to target extended properties of events, you'll also need to configure the types of your [`useAnalyticsEvent`](https://developers.vtex.com/docs/guides/faststore/analytics-use-analytics-event) callback function to expect an event of that type.
```ts
import { useAnalyticsEvent } from '@faststore/sdk'
import type { ExtendedEvents } from './types'
export const AnalyticsHandler = () => {
useAnalyticsEvent((event: ExtendedEvents) => {
/* ... */
})
/* ... */
return null
}
```
>ℹ️ By typing the callback function with the extended types, you can reference properties not natively provided by the Analytics module.
### Step 3 - Fire custom events
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.
```ts
import { useCallback } from 'react'
import { sendAnalyticsEvent } from '@faststore/sdk'
const MyComponent = () => {
const handleCustomEvent = useCallback(() => {
sendAnalyticsEvent({
name: 'custom_action',
isEcommerceEvent: false,
params: {
action_type: 'button_click',
component_name: 'MyComponent',
timestamp: new Date().toISOString()
}
})
}, [])
return <button onClick={handleCustomEvent}>Trigger Custom Event</button>
}
```
> ℹ️ 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.).
## Next steps
* Explore the [Analytics Overview](https://developers.vtex.com/docs/guides/faststore/analytics-overview) guide for more information on the Analytics module.
* Refer to the [Implementing custom newsletter analytics events](https://developers.vtex.com/docs/guides/faststore/analytics-implementing-custom-newsletter-analytics-events) guide for a practical example.
* Consult the documentation for [`sendAnalyticsEvent`](https://developers.vtex.com/docs/guides/faststore/analytics-send-analytics-event) and [`useAnalyticsEvent`](https://developers.vtex.com/docs/guides/faststore/analytics-use-analytics-event) for advanced usage.Was this feedback useful?
|
Grammar review summaryReview for
|
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Grammar review summaryReview for
|
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Grammar review summaryReview for
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| ## Usage | ||
|
|
||
| In the component related to the event, declare a callback function. In this function, define an event object with the desired event type (example: `add_to_cart`) and call `sendAnalyticsEvent`. Then, pass the related event as an argument. Finally, call the callback function in the event trigger (example: `onClick`). | ||
| 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`). |
There was a problem hiding this comment.
📝 [Grammar reviewer] reported by reviewdog 🐶
Using 'e.g.,' (exempli gratia) is more concise and commonly used in technical documentation than 'for example,'.
| 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`). | |
| In the event-related component, define a callback function that creates an event object with the desired type (e.g., `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`). |
| | `params` | `any` | Any type and value your custom event uses. | | ||
| | Property name | Type | Description | Default | | ||
| | ------------------- |-------- |---------------- |---------| | ||
| | `name` | `string` | The name of the event that appears in Analytics reports. The `name` does not need to follow any event name conventions related to natively supported events. | Required | |
There was a problem hiding this comment.
📝 [Grammar reviewer] reported by reviewdog 🐶
Replacing 'related to' with 'for' makes the sentence more concise and direct, improving readability.
| | `name` | `string` | The name of the event that appears in Analytics reports. The `name` does not need to follow any event name conventions related to natively supported events. | Required | | |
| | `name` | `string` | The name of the event that appears in Analytics reports. The `name` does not need to follow any event name conventions for natively supported events. | Required | |
|
|
||
| #### 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](https://www.typescriptlang.org/docs/handbook/2/generics.html) with the [`sendAnalyticsEvent`](https://developers.vtex.com/docs/guides/faststore/analytics-send-analytics-event) function. |
There was a problem hiding this comment.
📝 [Grammar reviewer] reported by reviewdog 🐶
Adding an apostrophe-s ('s) to 'TypeScript' clarifies possession and makes the phrase 'TypeScript's generics' sound more natural when referring to a feature of the language.
| 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](https://www.typescriptlang.org/docs/handbook/2/generics.html) with the [`sendAnalyticsEvent`](https://developers.vtex.com/docs/guides/faststore/analytics-send-analytics-event) function. | |
| If your event is related to an existing one, you can extend relevant types from the Analytics module. You can do this by using TypeScript's generics with the [`sendAnalyticsEvent`](https://developers.vtex.com/docs/guides/faststore/analytics-send-analytics-event) function. |
| ``` | ||
|
|
||
| Note that to target extended properties of events, you'll also need to configure the types of your [`useAnalyticsEvent`](https://developers.vtex.com/docs/guides/faststore/analytics-use-analytics-event) callback function to expect an event of such type. | ||
| Note that to target extended properties of events, you'll also need to configure the types of your [`useAnalyticsEvent`](https://developers.vtex.com/docs/guides/faststore/analytics-use-analytics-event) callback function to expect an event of that type. |
There was a problem hiding this comment.
📝 [Grammar reviewer] reported by reviewdog 🐶
The verb 'access' is more precise than 'target' in the context of working with properties of an object, improving clarity.
| Note that to target extended properties of events, you'll also need to configure the types of your [`useAnalyticsEvent`](https://developers.vtex.com/docs/guides/faststore/analytics-use-analytics-event) callback function to expect an event of that type. | |
| Note that to access extended properties of events, you'll also need to configure the types of your [`useAnalyticsEvent`](https://developers.vtex.com/docs/guides/faststore/analytics-use-analytics-event) callback function to expect an event of that type. |
There was a problem hiding this comment.
📝 [Grammar reviewer] reported by reviewdog 🐶
Rephrasing to 'it aims to handle' makes the sentence more concise and less clunky, improving flow and readability.
There was a problem hiding this comment.
📝 [Grammar reviewer] reported by reviewdog 🐶
Clarifying 'it' as 'this functionality' makes the sentence more precise and less ambiguous, improving clarity.
carolinamenezes
left a comment
carolinamenezes
left a comment
There was a problem hiding this comment.
Achei um pouco misturado o que deveria ser referência e guia de implementação
| | `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` | | ||
|
|
||
| ### Using custom events without ecommerce structure |
There was a problem hiding this comment.
| ### Using custom events without ecommerce structure | |
| ### `isEcommerceEvent` |
| } | ||
| ``` | ||
|
|
||
| #### Example: Ecommerce event (default behavior) |
There was a problem hiding this comment.
| #### Example: Ecommerce event (default behavior) | |
| #### GA4 ecommerce event (`isEcommerceEvent: true`) |
| ``` | ||
|
|
||
| #### Example: Ecommerce event (default behavior) | ||
|
|
There was a problem hiding this comment.
| Use `isEcommerceEvent: true` (default) to format the event according to the GA4 ecommerce data model, wrapping all parameters inside the ecommerce object. Take the following example | |
|
|
||
| By default, `sendAnalyticsEvent` wraps event parameters in an `ecommerce` object to follow the [Google Analytics 4 ecommerce events](https://support.google.com/analytics/answer/14434488?hl=en) 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](https://support.google.com/analytics/answer/14240153?hl=en). | ||
|
|
||
| #### Example: Custom event with `isEcommerceEvent: false` |
There was a problem hiding this comment.
| #### Example: Custom event with `isEcommerceEvent: false` | |
| #### Custom events without GA4 `ecommerce` (`isEcommerceEvent: false`) |
| } | ||
| ``` | ||
|
|
||
| ## Exporting custom event types with generics |
There was a problem hiding this comment.
| ## Exporting custom event types with generics | |
| ## Typed custom events |
There was a problem hiding this comment.
Só faz sentido para isCommerce: false?
Caso positivo, mover para a categoria correspondente
| To create a custom event interface, use the `sendAnalyticsEvent` function. This function requires the event to include the following properties: | ||
|
|
||
| | Property name | Type | Description | | ||
| | ------------------- |-------- |---------------- | | ||
| | `name` | `string` | The name of the event that appears in Analytics reports. The `name` doesn't need to follow any event name conventions related to natively supported events. | | ||
| | `params` | `any` | Any type and value your custom event uses. | | ||
| | Property name | Type | Description | Default | | ||
| | ------------------- |-------- |---------------- |---------| | ||
| | `name` | `string` | The name of the event that appears in Analytics reports. The `name` does not need to follow any event name conventions related to natively supported events. | Required | | ||
| | `params` | `any` | Any type and value for your custom event. | Required | | ||
| | `isEcommerceEvent` | `boolean` | 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](https://support.google.com/analytics/answer/14240153?hl=en). | `true` | |
There was a problem hiding this comment.
Não precisa repetir tudo. Só utilizar o link da doc de referência e explicar que, nessa doc, é usado isEcommerceEvent: false
Types of changes
Release note: https://vtex-dev.atlassian.net/browse/EDU-16613