Programmatic Tracking API

// Wait for PixelFlow to initialize, then track event
const trackPurchase = async () => {
  if (
    window.pixelFlow?.trackEvent &&
    window.pixelFlow?.utils?.normalizeCustomerData
  ) {
    try {
      const normalizedCustomerData =
        await window.pixelFlow.utils.normalizeCustomerData(customerData); // normalizes data 
      window.pixelFlow.trackEvent("Purchase", payload, normalizedCustomerData);
    } catch (error) {
      console.error("PixelFlow: Error tracking Purchase event", error);
    }
  } else {
    console.warn("PixelFlow: API not ready, retrying...");
    // Retry after 1 second if not ready
    setTimeout(trackPurchase, 1000);
  }
};

trackEvent(
  eventName: string,
  customData: CustomData,
  userData: UserData
): Promise<boolean>

{
  value?: number;             // Monetary value (required for Purchase, recommended for value optimization)
  currency?: string;          // ISO 4217 currency code (e.g., "USD", "EUR", "GBP")
  content_ids?: string[];     // Product SKUs or identifiers
  content_name?: string;      // Product or content name
  content_type?: 'product' | 'product_group';
  contents?: ContentItem[];   // Detailed product information
  num_items?: number;         // Quantity of items
  searchStr?: string;         // Search string (Search events only)
}

{
  em: string; // Email address (normalization required)
  ph: string; // Phone number (normalization required)
  fn: string; // First name (normalization required)
  ln: string; // Last name (normalization required)
}

// Normalize entire customer data object
const normalizedData = await window.pixelFlow.utils.normalizeCustomerData({
  em: "[email protected]",
  fn: "  John  ",
  ln: "Doe",
  ph: "(555) 123-4567",
});
// Returns normalized and ready-to-use object

// Email normalization (lowercase, trim)
const normalizedEmail =
  window.pixelFlow.utils.normalizeEmail("[email protected]");
// Returns: '[email protected]'

// Name normalization (lowercase, trim)
const normalizedName = window.pixelFlow.utils.normalizeName("  John  ");
// Returns: 'john'

// Phone normalization (digits only, add country code)
const normalizedPhone = window.pixelFlow.utils.normalizePhone(
  "+1 (555) 123-4567",
  "US"
);
// Returns: '15551234567'

// Generic alphanumeric lowercase (for city, state, etc.)
const normalizedCity = window.pixelFlow.utils.normalizeAlnumLower("New York");
// Returns: 'newyork'

// Postal code normalization
const normalizedZip = window.pixelFlow.utils.normalizePostal("94103-1234");
// Returns: '94103'

// Country code normalization
const normalizedCountry =
  window.pixelFlow.utils.normalizeCountry("United States");
// Returns: 'us'

/**
 * Content item for product details
 */
export type ContentItem = {
  /** Product ID or SKU */
  id: string;
  /** Quantity of the product */
  quantity: number;
  /** Price of the individual item */
  item_price?: number;
  /** "in_store", "curbside", or "home_delivery" */
  delivery_category?: 'in_store' | 'curbside' | 'home_delivery';
};

/**
 * CustomData type for Meta Conversions API
 * Contains event-specific data like product information and pricing.
 * Only the fields listed below are accepted. Any other property causes
 * the event endpoint to return HTTP 400 and the event is not stored.
 */
export type CustomData = {
  /** Monetary value associated with the event (required for Purchase) */
  value?: number;
  /** ISO 4217 currency code (e.g., "USD", "EUR", "GBP") */
  currency?: string;
  /** Product SKUs or identifiers */
  content_ids?: string[];
  /** Product or content name */
  content_name?: string;
  /** "product" or "product_group" */
  content_type?: 'product' | 'product_group';
  /** Array of product items with details */
  contents?: ContentItem[];
  /** Total number of items */
  num_items?: number;
  /** Search string (Search events only) */
  searchStr?: string;
};

/**
 * UserData type for Meta Conversions API
 * Customer information for better ad targeting and attribution
 * IMPORTANT: Data must be normalized before passing to trackEvent (use utils)
 * Hashing is handled automatically by the script
 */
export type UserData = {
  /**
   * Email - must be normalized (lowercase, trimmed)
   * Use window.pixelFlow.utils.normalizeCustomerData()
   * @example "[email protected]" (normalized)
   */
  em?: string;
  /**
   * Phone - must be normalized (digits only, with country code)
   * Use window.pixelFlow.utils.normalizeCustomerData()
   * @example "16505551212" (normalized)
   */
  ph?: string;
  /**
   * First name - must be normalized (lowercase, trimmed)
   * Use window.pixelFlow.utils.normalizeCustomerData()
   * @example "john" (normalized)
   */
  fn?: string;
  /**
   * Last name - must be normalized (lowercase, trimmed)
   * Use window.pixelFlow.utils.normalizeCustomerData()
   * @example "smith" (normalized)
   */
  ln?: string;
  /**
   * Client User Agent
   * Automatically captured by PixelFlow if not provided
   */
  client_user_agent?: string;
};

/**
 * PixelFlow global type for window.pixelFlow
 */
export type PixelFlow = {
  version: string;
  initialized: boolean;
  trackEvent: (eventName: string, customData: CustomData, userData: UserData) => Promise<boolean>;
  utils: {
    /** Normalize entire customer data object (required before trackEvent, hashing automatic) */
    normalizeCustomerData: (data: Partial<UserData>) => Promise<Partial<UserData>>;
    /** Normalize email: lowercase, trim whitespace */
    normalizeEmail: (email: string) => string;
    /** Normalize name: lowercase, trim whitespace */
    normalizeName: (name: string) => string;
    /** Normalize phone: digits only, add country code if needed */
    normalizePhone: (phone: string, countryCode?: string) => string;
    /** Normalize to alphanumeric lowercase */
    normalizeAlnumLower: (value: string) => string;
    /** Normalize postal code: remove spaces and dashes */
    normalizePostal: (postal: string) => string;
    /** Normalize country: 2-letter ISO code lowercase */
    normalizeCountry: (country: string) => string;
  };
};

declare global {
  interface Window {
    pixelFlow?: PixelFlow;
  }
}

// After form validation succeeds on server
async function onFormValidationSuccess(formData) {
  // Prepare user data from form
  const userData = await window.pixelFlow.utils.normalizeCustomerData({
    em: formData.email, 
    fn: formData.firstName, 
    ln: formData.lastName,
    ph: formData.phone,
  });

  // Prepare custom data
  const customData = {
    value: 500, // Estimated lead value
    currency: "USD",
  };

  // Track the lead event
  const success = await window.pixelFlow.trackEvent(
    "Lead",
    customData,
    userData
  );

  if (success) {
    console.log("Lead tracked successfully");
  } else {
    console.error("Failed to track lead");
  }
}