trackExponeaEvent Method

trackExponeaEvent Method

The trackExponeaEvent method is a service for tracking user interactions and events in your application and sending them to the Exponea analytics platform. It includes features like consent verification, data transformation, and specialized event tracking for ecommerce scenarios.

Type Definitions

ExponeaEventType

A string representing valid event types:

type ExponeaEventType =
  | "view_item"
  | "view_category"
  | "cart_update"
  | "checkout"
  | "login"
  | "signup";

ExponeaEventData

Defines the structure for an event's properties:

type ExponeaEventData = Record<string, any>;

Method Definition

trackExponeaEvent

trackExponeaEvent(
eventName: ExponeaEventType,
eventData: ExponeaEventData = {},
debug: boolean = false
): void

Tracks and sends events to Exponea after verifying user consent for analytics.

Parameters

1. eventName (ExponeaEventType): The name of the event to track (e.g., 'login', 'view_item', 'cart_update').
2. eventData (ExponeaEventData, default: {}): An object containing the data associated with the event.
3. debug (boolean, default: false): If true, logs the tracked event and data to the console.

Return Type

• void: The method does not return any value.

How It Works

1. Consent Verification:
   • Checks if the user has granted consent for analytical cookies using rootStore.checkConsent(OneTrustCookieGroup.Analytical).
   • If consent is not given, the function returns immediately, and no event is tracked.
2. Client-Side Verification:
   • Verifies that the code is running on the client-side (import.meta.client).
   • Checks that the Exponea SDK is available (window.exponea).
   • Logs warnings if these conditions are not met.
3. Special Event Handling:
   • For 'view_item' events: Transforms product data using the internal transformProductData helper function.
   • For other events: Sends the eventData object directly to Exponea.
4. Event Tracking:
   • Calls window.exponea.track(eventName, eventData) to send the event to Exponea.
5. Debugging:
   • If debug is true, logs the event name and data to the console.

Supporting Methods

postTrolleyUpdate

postTrolleyUpdate(actionType: string, line: TrolleyLineItem): Promise<void>

Tracks updates to the user's shopping cart (trolley), such as adding or removing items.

Parameters

1. actionType (string): Describes the action performed (e.g., 'add', 'remove').
2. line (TrolleyLineItem): An object representing the trolley line item that was affected.

How It Works

1. Dynamically imports the trolleyStore.
2. Extracts product, channel, and quantity from the line parameter.
3. Transforms product data using the internal transformProductDataV2 helper function.
4. Calculates cart totals (price, tax, quantity, product list).
5. Creates a comprehensive tracking object with action details, product details, and cart state.
6. Calls trackExponeaEvent('cart_update', exponeaTrackingObject).

trackCheckoutStepEvent

trackCheckoutStepEvent({
trolleyStore,
checkoutStore,
stepName,
stepNumber,
trolleyDetails,
extras
}: CheckoutStepEventParams): void

Tracks the user's progression through the checkout process.

Parameters

An object containing:

• trolleyStore (any): Used to get cart totals, discounts, and product details.
• checkoutStore (any): Used to get shipping costs.
• stepName (string): The name of the checkout step (e.g., 'Shipping Address', 'Payment').
• stepNumber (number): The numerical order of the step (e.g., 1, 2).
• trolleyDetails (any): Pre-formatted product lists for Exponea.
• extras (Record<string, any>, optional): Additional data to be merged into the event payload.

How It Works

1. Constructs a tracking object with totals, delivery cost, step info, product lists, and custom data.
2. Calls trackExponeaEvent('checkout', exponeaTrackingObject).

Helper Functions (Internal)

Example Usage

Tracking a Product View

trackExponeaEvent("view_item", this.product);

Tracking a User Login

trackExponeaEvent("login", {
  email: authStore.user.email,
  u_id: authStore.user.id,
});

Tracking a Cart Update

postTrolleyUpdate("add", addedLineItem);

Tracking a Checkout Step

trackCheckoutStepEvent({
  trolleyStore,
  checkoutStore,
  stepName: "Payment",
  stepNumber: 3,
  trolleyDetails: currentTrolleyDetails,
  extras: {
    payment_method_selected: "Credit Card",
  },
});

Dependencies & Prerequisites

• Exponea SDK: Must be loaded and initialized (window.exponea must exist).
• Cookie Consent: Must be managed (e.g., with OneTrust and useRootStore().checkConsent).