Event Types

Web Pixels can subscribe to these storefront events. Each event includes specific data relevant to the customer action.

Standard Events

Event Name	Trigger
page_viewed	Customer views a page.
product_viewed	Customer views a product page.
product_added_to_cart	Customer adds a product to cart.
product_removed_from_cart	Customer removes a product from cart.
cart_viewed	Customer views the cart.
checkout_started	Customer starts the checkout process.
checkout_completed	Customer completes a purchase.
search_submitted	Customer submits a search query.
customer_registered	A new customer registers.

Subscribing to Events

import { register } from "@qumra/web-pixels-extension";

register(async ({ api }) => {
  // Single event
  api.on("page_viewed", (event) => {
    console.log(event.data);
  });

  // Multiple events
  api.on("product_viewed", handleProductView);
  api.on("product_added_to_cart", handleAddToCart);
  api.on("checkout_completed", handlePurchase);

  // All events at once
  api.on("all_events", (event) => {
    console.log(event.name, event.data);
  });
});

Event Data Structures

page_viewed

{
  url: string;              // Current page URL
  referrer: string;         // Referring URL
  title: string;            // Page title
}

product_viewed

{
  product_id: string;       // Product ID
  product_name: string;     // Product title
  product_price: number;    // Product price
  product_type: string;     // Product category/type
  currency: string;         // Currency code (e.g. "SAR")
  variant_id?: string;      // Selected variant ID
}

product_added_to_cart

{
  product_id: string;       // Product ID
  product_name: string;     // Product title
  product_price: number;    // Product price
  quantity: number;         // Quantity added
  currency: string;         // Currency code
  variant_id?: string;      // Variant ID
  cart_id?: string;         // Cart ID
}

checkout_started

{
  currency: string;         // Currency code
  value: number;            // Cart total value
  items: Array<{
    product_id: string;
    product_name: string;
    quantity: number;
    price: number;
  }>;
}

checkout_completed

{
  currency: string;         // Currency code
  response: {
    total: number;          // Order total
    order_id: string;       // Order ID
    items: Array<{
      product_id: string;
      product_name: string;
      quantity: number;
      price: number;
    }>;
  };
}

search_submitted

{
  query: string;            // Search query text
}

customer_registered

{
  customer_id: string;      // New customer ID
  email?: string;           // Customer email
}

Common Data Types

MoneyV2

interface MoneyV2 {
  amount: string;           // Numeric amount as string
  currencyCode: string;     // ISO 4217 currency code
}

MailingAddress

interface MailingAddress {
  firstName?: string;
  lastName?: string;
  address1?: string;
  address2?: string;
  city?: string;
  province?: string;
  country?: string;
  zip?: string;
  phone?: string;
}

Custom Events

Apps can also define and subscribe to custom events:

api.on("custom_event", (event) => {
  const { customData } = event.data;
  // Handle custom event
});