Web Pixel Examples

Real-world examples of web pixel implementations for popular tracking platforms.

Google Tag (GA4)

extensions/google-tag/src/index.ts

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

const EVENT_MAP: Record<string, string> = {
  page_viewed: "page_view",
  product_viewed: "view_item",
  product_added_to_cart: "add_to_cart",
  checkout_started: "begin_checkout",
  checkout_completed: "purchase",
  search_submitted: "search",
  customer_registered: "sign_up",
};

register(async ({ settings, browser, api }) => {
  // Parse pixel configuration from settings
  const pixels = JSON.parse(settings.pixels || "[]");
  const activePixels = pixels.filter(
    (p: any) => p.enabled && p.id?.trim()
  );

  if (activePixels.length === 0) return;

  // Load gtag.js with the first pixel's ID
  await browser.loadScript(
    `https://www.googletagmanager.com/gtag/js?id=${activePixels[0].id}`
  );

  // Initialize the dataLayer and gtag function
  window.dataLayer = window.dataLayer || [];
  function gtag(...args: any[]) {
    window.dataLayer.push(args);
  }
  gtag("js", new Date());

  // Configure each pixel
  for (const pixel of activePixels) {
    gtag("config", pixel.id);
  }

  // Listen to all events and map to GA4
  api.on("all_events", (event) => {
    const gaEvent = EVENT_MAP[event.name];
    if (!gaEvent) return;

    // Check if this event is enabled for any pixel
    const enabledPixels = activePixels.filter(
      (p: any) => p.events?.[event.name]
    );
    if (enabledPixels.length === 0) return;

    const eventData = mapEventData(event.name, event.data);

    for (const pixel of enabledPixels) {
      gtag("event", gaEvent, { ...eventData, send_to: pixel.id });
    }
  });
});

function mapEventData(eventName: string, data: any) {
  switch (eventName) {
    case "product_viewed":
      return {
        currency: data.currency || "SAR",
        value: data.product_price,
        items: [
          {
            item_id: data.product_id,
            item_name: data.product_name,
            item_category: data.product_type,
            price: data.product_price,
          },
        ],
      };

    case "product_added_to_cart":
      return {
        currency: data.currency || "SAR",
        value: data.product_price * data.quantity,
        items: [
          {
            item_id: data.product_id,
            item_name: data.product_name,
            quantity: data.quantity,
            price: data.product_price,
          },
        ],
      };

    case "checkout_completed":
      return {
        currency: data.currency,
        value: data.response?.total,
        transaction_id: data.response?.order_id,
        items: data.response?.items?.map((item: any) => ({
          item_id: item.product_id,
          item_name: item.product_name,
          quantity: item.quantity,
          price: item.price,
        })),
      };

    case "search_submitted":
      return { search_term: data.query };

    default:
      return data;
  }
}

---

Meta Pixel (Facebook)

extensions/meta-pixel/src/index.ts

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

const EVENT_MAP: Record<string, string> = {
  page_viewed: "PageView",
  product_viewed: "ViewContent",
  product_added_to_cart: "AddToCart",
  checkout_started: "InitiateCheckout",
  checkout_completed: "Purchase",
  search_submitted: "Search",
  customer_registered: "CompleteRegistration",
};

register(async ({ settings, browser, api }) => {
  const pixels = JSON.parse(settings.pixels || "[]");
  const activePixels = pixels.filter(
    (p: any) => p.enabled && p.id?.trim()
  );

  if (activePixels.length === 0) return;

  // Load Meta Pixel SDK
  await browser.loadScript("https://connect.facebook.net/en_US/fbevents.js");

  // Initialize each pixel
  for (const pixel of activePixels) {
    fbq("init", pixel.id);
  }

  // Track page view for all pixels
  fbq("track", "PageView");

  // Listen to events
  api.on("all_events", (event) => {
    const fbEvent = EVENT_MAP[event.name];
    if (!fbEvent || fbEvent === "PageView") return;

    const enabledPixels = activePixels.filter(
      (p: any) => p.events?.[event.name]
    );
    if (enabledPixels.length === 0) return;

    const eventData = mapEventData(event.name, event.data);
    fbq("track", fbEvent, eventData);
  });
});

function mapEventData(eventName: string, data: any) {
  switch (eventName) {
    case "product_viewed":
      return {
        content_ids: [data.product_id],
        content_name: data.product_name,
        content_type: "product",
        currency: data.currency,
        value: data.product_price,
      };

    case "product_added_to_cart":
      return {
        content_ids: [data.product_id],
        content_name: data.product_name,
        content_type: "product",
        currency: data.currency,
        value: data.product_price * data.quantity,
      };

    case "checkout_completed":
      return {
        currency: data.currency,
        value: data.response?.total,
        content_ids: data.response?.items?.map(
          (i: any) => i.product_id
        ),
        content_type: "product",
      };

    case "search_submitted":
      return { search_string: data.query };

    default:
      return {};
  }
}

---

Common Pattern

All pixel implementations follow the same structure:

1. Parse settings -- Get pixel IDs and configuration from settings
2. Load SDK -- Use browser.loadScript() to load the vendor's tracking script
3. Initialize pixels -- Call the vendor's init function with each pixel ID
4. Map events -- Create a mapping from Qumra events to vendor events
5. Subscribe -- Use api.on("all_events", ...) to listen and forward events

Event Mapping Reference

Qumra Event	Google (GA4)	Meta (Facebook)	TikTok	Pinterest	Snapchat
page_viewed	page_view	PageView	PAGE_VIEW	pagevisit	PAGE_VIEW
product_viewed	view_item	ViewContent	VIEW_CONTENT	pagevisit	VIEW_CONTENT
product_added_to_cart	add_to_cart	AddToCart	ADD_TO_CART	addtocart	ADD_CART
checkout_started	begin_checkout	InitiateCheckout	CHECKOUT	checkout	START_CHECKOUT
checkout_completed	purchase	Purchase	PURCHASE	checkout	PURCHASE
search_submitted	search	Search	SEARCH	search	SEARCH
customer_registered	sign_up	CompleteRegistration	COMPLETE_REGISTRATION	signup	SIGN_UP

Admin Dashboard Pattern

Most pixel apps share a common admin interface pattern:

• Store pixel configurations in MongoDB (pixel ID, name, enabled status, selected events)
• Support multiple pixels per app (up to 4)
• Allow toggling which events each pixel tracks
• Use the useSaveBar() hook for save/discard UX
• Use GraphQL mutations (CreateWebPixel, UpdateWebPixel) to sync pixel state with the platform