uni-analytics-sdk/src/providers/GoogleAnalyticsProvider/events/GA4EventTemplates.ts

A universal SDK for analytics and logging.

/**
 * @fileoverview This file contains strongly-typed event creators for standard
 * Google Analytics 4 events, particularly for e-commerce. Using these templates
 * ensures that the data sent to GA4 via the SDK's `track` method is valid and
 * conforms to Google's official schema.
 */

// Based on the official Google Analytics 4 developer documentation.

/**
 * Represents a single item in an e-commerce transaction.
 */
export interface GA4Item {
    item_id?: string;
    item_name?: string;
    affiliation?: string;
    coupon?: string;
    discount?: number;
    index?: number;
    item_brand?: string;
    item_category?: string;
    item_category2?: string;
    item_category3?: string;
    item_category4?: string;
    item_category5?: string;
    item_list_id?: string;
    item_list_name?: string;
    item_variant?: string;
    location_id?: string;
    price?: number;
    quantity?: number;
  }
  
  // --- E-commerce Event Parameter Interfaces ---
  
  export interface PurchaseParams {
    transaction_id: string;
    value: number;
    currency: string;
    items: GA4Item[];
    affiliation?: string;
    coupon?: string;
    shipping?: number;
    tax?: number;
  }
  
  export interface RefundParams {
    transaction_id: string;
    value: number;
    currency: string;
    items?: GA4Item[];
    affiliation?: string;
    coupon?: string;
    shipping?: number;
    tax?: number;
  }
  
  export interface AddToCartParams {
    value: number;
    currency: string;
    items: GA4Item[];
  }
  
  export interface BeginCheckoutParams {
    value: number;
    currency: string;
    items: GA4Item[];
    coupon?: string;
  }
  
  export interface ViewItemParams {
      value: number;
      currency: string;
      items: GA4Item[];
  }
  
  // --- Lead Generation Event Parameter Interfaces ---
  
  export interface GenerateLeadParams {
      value: number;
      currency: string;
  }
  
  // --- Generic Event Parameter Interfaces ---
  
  export interface SignUpParams {
      method: 'Google' | 'Email' | 'Facebook' | string;
  }
  
  export interface LoginParams {
      method: 'Google' | 'Email' | 'Facebook' | string;
  }
  
  /**
   * A collection of functions to create standardized GA4 event objects.
   * These can be passed directly to the `sdk.track()` method.
   */
  export const ga4 = {
    /**
     * Creates a valid 'purchase' event payload.
     */
    purchase: (params: PurchaseParams) => ({
      eventName: 'purchase',
      properties: params,
    }),
  
    /**
     * Creates a valid 'refund' event payload.
     */
    refund: (params: RefundParams) => ({
      eventName: 'refund',
      properties: params,
    }),
  
    /**
     * Creates a valid 'add_to_cart' event payload.
     */
    addToCart: (params: AddToCartParams) => ({
      eventName: 'add_to_cart',
      properties: params,
    }),
  
    /**
     * Creates a valid 'begin_checkout' event payload.
     */
    beginCheckout: (params: BeginCheckoutParams) => ({
      eventName: 'begin_checkout',
      properties: params,
    }),
  
      /**
     * Creates a valid 'view_item' event payload.
     */
    viewItem: (params: ViewItemParams) => ({
      eventName: 'view_item',
      properties: params,
    }),
  
    /**
     * Creates a valid 'generate_lead' event payload.
     */
    generateLead: (params: GenerateLeadParams) => ({
      eventName: 'generate_lead',
      properties: params,
    }),
  
    /**
     * Creates a valid 'sign_up' event payload.
     */
    signUp: (params: SignUpParams) => ({
      eventName: 'sign_up',
      properties: params,
    }),
  
      /**
     * Creates a valid 'login' event payload.
     */
    login: (params: LoginParams) => ({
      eventName: 'login',
      properties: params,
    }),
  };