logEvent Method

logEvent Method

The logEvent method is a utility for tracking and logging user interactions and system events in your application. It integrates with Google Tag Manager (GTM) and DataDog and now includes features like event queuing, consent handling, and support for ecommerce event.

Type Definitions

Event

An expanded enumerated type representing valid event actions:

type Event =
  | "click"
  | "page_view"
  | "form_submit"
  | "error"
  | "Sign In"
  | "Sign Up"
  | "PageLoaded"
  | "scroll"
  | "input";

GenericEventOptions

Defines the structure for an event's properties:

interface GenericEventOptions {
  ecommerce?: any; // Ecommerce-specific payload
  eventName: string;
  eventProperties: any;
  eventAction: Event;
  eventLabel: string;
  eventInteraction: boolean;
}

EventOptions

A wrapper for optional event parameters:

type EventOptions = {
  options?: GenericEventOptions;
};

Method Definition

logEvent

logEvent(eventParameters: EventOptions, skipDataDog = false): void Tracks and logs events through GTM and/or DataDog, depending on the configuration and user consent.

Parameters

1. eventParameters (EventOptions):Contains detailed data describing the event.
2. skipDataDog (boolean, default: false): Determines whether the event should be logged to DataDog.

Return Type

• void: The method does not return any value.

How It Works

1. Google Tag Manager (GTM) Integration:
   • Constructs and pushes a payload to GTM using the gtm.trackEvent method.
   • Resets GTM dataLayer for certain events (e.g. virtual_pageview, virtual_event) and before ecommerce events.
2. DataDog Integration:
   • Checks for the availability of the DataDog client or initializes it if not already available.
   • Logs the event to DataDog unless skipDataDog is set to true.

Consent-Aware Queuing :

• If consent has not been processed (hasConsentProcessed === false), events are temporarily stored in a queue.
• Once consent is granted, all queued events are processed in FIFO order via processQueuedEvents().

Ecommerce Events Support :

• Ecommerce events can include an additional ecommerce object.
• Values from ecommerce (e.g., value) are included in the final payload for GTM.

Mapping Event Properties to GTM

The properties in GenericEventOptions are mapped as follows:

Supporting Methods :

• processQueuedEvents(): void : Processes all queued events once user consent is acknowledged.
• logDatadogAction(name: string, options: any): void : Logs custom actions to DataDog RUM (if available on the client).
• logPageView(params): void : Logs a virtual pageview and navigation journey, Useful for SPA routing.

logPageView({
  user,
  toPath: "/home",
  fromPath: "/login",
  locale: "nl-NL",
  isIncVat: true,
});

Example Usage

Logging a Click Event

logEvent({
  options: {
    eventName: "button_click",
    eventProperties: { buttonId: "submit-btn" },
    eventAction: "click",
    eventLabel: "Submit Button",
    eventInteraction: true,
    eventValue: 1,
  },
});

Logging an Event with Ecommerce Data

logEvent({
  options: {
    eventName: "view_item",
    eventAction: "page_view",
    eventLabel: "Product Page",
    eventInteraction: true,
    eventProperties: { productId: "123" },
    ecommerce: {
      value: 99.99,
      currency: "EUR",
      items: [{ id: "123", name: "Widget" }],
    },
  },
});

• Learn more about ecommerce events Here

Skipping DataDog Logging

logEvent(
  {
    options: {
      eventName: "form_submit",
      eventProperties: { formId: "signup-form" },
      eventAction: "form_submit",
      eventLabel: "Signup Form",
      eventInteraction: true,
    },
  },
  true // Skip logging to DataDog
);

Notes

• Ensure GTM is properly initialized before calling logEvent.
• For DataDog integration, replace the placeholder logic with actual DataDog client initialization and logging code.
• Events are only processed after user consent is acknowledged (set via processQueuedEvents()).
• The event queue ensures no data is lost during the consent wait state.
• Default values are provided for some parameters (e.g., eventName defaults to 'click-default' if not specified).