Web Pixels (@qumra/web-pixels-extension)

Web Pixels allow your app to run tracking and analytics scripts on the storefront. They provide a sandboxed environment for loading third-party scripts (Google Analytics, Meta Pixel, TikTok Pixel, etc.) and listening to customer events.

Installation

npm

npm install @qumra/web-pixels-extension

pnpm

pnpm install @qumra/web-pixels-extension

Yarn

yarn add @qumra/web-pixels-extension

Quick Example

extensions/my-pixel/src/index.ts

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

register(async ({ settings, browser, api }) => {
  // 1. Load the tracking script
  await browser.loadScript("https://example.com/analytics.js");

  // 2. Initialize with your settings
  window.analytics.init(settings.pixelId);

  // 3. Listen to all storefront events
  api.on("all_events", (event) => {
    window.analytics.track(event.name, event.data);
  });
});

How Web Pixels Work

1. You create a web pixel extension using qumra app extension
2. The pixel code runs in a sandboxed environment on the storefront
3. It receives settings (configured from the app's admin dashboard)
4. It subscribes to storefront events (page views, add to cart, purchases, etc.)
5. It maps these events to third-party tracking calls

Creating a Web Pixel

qumra app extension
# Choose: Web Pixel

This creates:

extensions/my-pixel/
├── src/
│   └── index.ts          # Pixel entry point
├── dist/
│   └── index.js          # Built output (auto-generated)
├── manifest.json
└── package.json

Extension API

The register() callback receives an API object with:

register(async ({ settings, browser, api, init, customerPrivacy }) => {
  // ...
});

Property	Type	Description
settings	Record<string, string>	Extension settings from the app configuration.
browser	BrowserApi	Browser utilities for loading scripts.
api	PixelApi	Event subscription API.
init	object	Initialization data.
customerPrivacy	PrivacyApi	Customer privacy preferences.

api.on(eventName, callback)

Subscribe to storefront events:

// Listen to a specific event
api.on("page_viewed", (event) => {
  console.log("Page viewed:", event.data);
});

// Listen to all events
api.on("all_events", (event) => {
  console.log(event.name, event.data);
});

browser.loadScript(url)

Load an external script:

await browser.loadScript("https://www.googletagmanager.com/gtag/js?id=G-XXXXX");

Next Steps

• Event Types -- All available storefront events and their data structures.
• Examples -- Real-world examples of pixel implementations.