How to Install the Upstack Data Tracking Pixel

Get the Upstack pixel running on your site in under 5 minutes. This guide covers non-Shopify installations — if you’re on Shopify, use the Shopify app installation guide instead.

Installation

Add this code snippet to every page you want to track, just before the closing </head> tag:

<!-- Start UpstackData Pixel -->
<script src="https://prod2-cdn.upstackified.com/scripts/px/ups.min.js" async="true"></script>
<script>
  window._adqLoaded = 0;
  window._upsqueue = window._upsqueue || [];
  window._upstack = window._upstack || function () {
    window._upsqueue.push(arguments);
  };
  window._upstack('init', 'YOUR_PIXEL_ID'); // replace with your Pixel ID
  window._upstack('page');
</script>
<!-- End UpstackData Pixel -->

init alone does not send a page view — the _upstack('page') call after init is what records it.

Replace YOUR_PIXEL_ID with your actual pixel ID from the Upstack dashboard. Your pixel ID is a UUID, such as 58284d43-85f6-41fb-b2e0-f32f8ecb4e9b.

Where to Find Your Pixel ID

Log in to app.upstackdata.com
Open System → Events Manager
Copy the Pixel ID shown in the page header (UUID format: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX)

See How to find my Upstack Data Pixel ID for screenshots.

Where to Place the Code

Standard Websites

Place the snippet in your site’s <head> section on every page:

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>My Store</title>
  
  <!-- Start UpstackData Pixel -->
  <script src="https://prod2-cdn.upstackified.com/scripts/px/ups.min.js" async="true"></script>
  <script>
    window._adqLoaded = 0;
    window._upsqueue = window._upsqueue || [];
    window._upstack = window._upstack || function () {
      window._upsqueue.push(arguments);
    };
    window._upstack('init', 'YOUR_PIXEL_ID'); // replace with your Pixel ID
    window._upstack('page');
  </script>
  <!-- End UpstackData Pixel -->
</head>
<body>
  <!-- Your content -->
</body>
</html>

Single Page Applications (SPAs)

For React, Vue, Next.js, or other SPAs:

Add the snippet once in your main index.html or root layout
Track route changes manually (page views don’t fire automatically on navigation). The snippet already sends the first page view, so skip the initial render to avoid counting it twice.

// React Router example
import { useEffect, useRef } from 'react';
import { useLocation } from 'react-router-dom';

function usePageTracking() {
  const location = useLocation();
  const isFirstRender = useRef(true);

  useEffect(() => {
    if (isFirstRender.current) {
      isFirstRender.current = false; // the snippet already tracked this page
      return;
    }
    window._upstack('page');
  }, [location.pathname]);
}

// Next.js App Router example
'use client';
import { usePathname } from 'next/navigation';
import { useEffect, useRef } from 'react';

export function Analytics() {
  const pathname = usePathname();
  const isFirstRender = useRef(true);

  useEffect(() => {
    if (isFirstRender.current) {
      isFirstRender.current = false; // the snippet already tracked this page
      return;
    }
    window._upstack('page');
  }, [pathname]);

  return null;
}

Google Tag Manager

If you prefer GTM, create a Custom HTML tag:

Create a new tag with type Custom HTML
Paste the installation snippet
Set trigger to All Pages (or your preferred trigger)
Publish the container

Verifying Installation

Browser Console Check

Open your browser’s developer console (F12) and run:

// Check if pixel is loaded
typeof window._upstack === 'function'  // Should return: true

// Check initialization status
window._upsClient?._initialized  // Should return: true (after init completes)

// Check if queue exists
Array.isArray(window._upsqueue)  // Should return: true

Test a Page View

Manually fire a page view and check the Network tab:

window._upstack('page');

Look for a request to upstackified.com or upstackdata.com in the Network tab.

Pixel Helper Extension

Install the Upstack Pixel Helper Chrome extension for real-time event monitoring without using the console.

Quick Start: Common Tracking Patterns

Track a Page View

// Basic page view (auto-captures URL, title, referrer)
window._upstack('page');

// With custom properties
window._upstack('page', {
  page_category: 'product',
  collection: 'summer-2026'
});

Track a Product View

window._upstack('track', 'view_content', {
  items: [{ id: 'PRODUCT_123', name: 'Blue Running Shoes', price: 89.99 }],
  value: 89.99,
  currency: 'USD'
});

Track Add to Cart

window._upstack('track', 'add_to_cart', {
  items: [{ id: 'PRODUCT_123', name: 'Blue Running Shoes', price: 89.99, quantity: 1 }],
  value: 89.99,
  currency: 'USD'
});

Track a Purchase

window._upstack('track', 'purchase', {
  orderId: 'ORDER_789',
  value: 149.99,
  currency: 'USD',
  items: [
    { id: 'PRODUCT_123', name: 'Blue Running Shoes', price: 89.99, quantity: 1 },
    { id: 'PRODUCT_456', name: 'Running Socks', price: 60.00, quantity: 1 }
  ]
});

Always include orderId for purchase events — Upstack derives the event ID from it to deduplicate browser and server events, so you don’t need to pass a third argument. Pass product data in items[]; destination content IDs are built from it (top-level content_ids, num_items, and content_type aren’t read).

Identifying Users

User identification improves match quality with ad platforms and enables cross-device tracking.

Basic Identification

// Identify with email only (most common)
window._upstack('identify', null, {
  emails: ['customer@example.com']
});

// Identify with phone
window._upstack('identify', null, {
  phones: ['+15551234567']
});

// Full identification
window._upstack('identify', 'user_123', {
  emails: ['customer@example.com'],
  phones: ['+15551234567'],
  firstName: 'Jane',
  lastName: 'Doe'
});

Important: emails and phones are arrays, not single strings. This supports users with multiple contact methods.

When to Identify

Call identify() when you capture user information:

Newsletter signup form submission
Account registration
Checkout (when email is entered)
Login

// Example: Newsletter form
document.querySelector('#newsletter-form').addEventListener('submit', (e) => {
  const email = e.target.querySelector('[name="email"]').value;
  window._upstack('identify', null, { emails: [email] });
});

Complete E-commerce Example

Here’s a full example tracking the customer journey:

// 1. Page view — sent on every page load by the install snippet's _upstack('page') call

// 2. Product view (on product page)
window._upstack('track', 'view_content', {
  items: [{ id: 'SKU-001', name: 'Premium Widget', price: 49.99 }],
  value: 49.99,
  currency: 'USD'
});

// 3. Add to cart (on button click)
document.querySelector('.add-to-cart').addEventListener('click', () => {
  window._upstack('track', 'add_to_cart', {
    items: [{ id: 'SKU-001', name: 'Premium Widget', price: 49.99, quantity: 1 }],
    value: 49.99,
    currency: 'USD'
  });
});

// 4. Begin checkout (on checkout page)
window._upstack('track', 'initiate_checkout', {
  items: [{ id: 'SKU-001', name: 'Premium Widget', price: 49.99, quantity: 1 }],
  value: 49.99,
  currency: 'USD'
});

// 5. Identify user (when email captured at checkout)
window._upstack('identify', null, {
  emails: ['customer@example.com']
});

// 6. Purchase (on thank-you page)
window._upstack('track', 'purchase', {
  orderId: 'ORD-12345',
  value: 49.99,
  currency: 'USD',
  items: [{ id: 'SKU-001', name: 'Premium Widget', price: 49.99, quantity: 1 }]
});

Troubleshooting

Pixel Not Firing

Check if the script is loading

Open Network tab in DevTools and look for ups.min.js. If it’s not loading:

Verify the script URL is correct
Check for ad blockers or privacy extensions
Ensure the snippet is in the <head>, not blocked by CSP

Check initialization

Run in console:

console.log('_upstack exists:', typeof window._upstack === 'function');
console.log('_upsClient exists:', typeof window._upsClient === 'object');
console.log('Initialized:', window._upsClient?._initialized);

All should return true after the page loads.

Verify pixel ID

Ensure your pixel ID:

Is a UUID (format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX)
Matches exactly what’s in your dashboard
Has no extra spaces or characters

Check for JavaScript errors

Look for errors in the Console tab. Common issues:

Calling _upstack before defining the queue function
Syntax errors in your tracking code
Conflicts with other scripts

Events Not Appearing in Dashboard

Wait a few minutes

Events can take a few minutes to appear in the dashboard. Check the Real-Time Events feed section of System → Events Manager for real-time data.

Check the Network tab

Look for outgoing requests after firing an event. You should see a POST request to the tracking endpoint.

Verify event names

Use standard event names like page_view, view_content, add_to_cart, purchase. Custom event names work but may not map to standard destination events.

Check for bot detection

The pixel automatically filters bot traffic. If you’re testing with automated tools, events may be ignored.

Common Mistakes

Issue	Solution
Using `upstack()` instead of `_upstack()`	The correct global is `window._upstack()` with underscore
Passing `email` instead of `emails: []`	Identity fields use arrays: `{ emails: ['user@example.com'] }`
Missing `currency` on purchase events	Always include `currency: 'USD'` (or your currency code)
Missing `orderId` on purchases	Include `orderId` (not `order_id`) for deduplication across browser/server events
Not tracking SPA navigation	Call `_upstack('page')` on route changes

JavaScript SDK Reference

Full API documentation for all methods and options.

Standard Events

Reference for all standard event types and their properties.

Properties & Context

Complete reference for item arrays, customer data, and auto-captured fields.

Identity Resolution

How user identification enables cross-device tracking.

Custom Events

Create events beyond the standard taxonomy for your needs.

Connect Destinations

Send events to Meta, Google, TikTok, Klaviyo, and more.

SDK

IDENTITY

AUTOMATIC TRACKING

How to Install the Upstack Data Tracking Pixel

Installation

Where to Find Your Pixel ID

Where to Place the Code

Standard Websites

Single Page Applications (SPAs)

Google Tag Manager

Verifying Installation

Browser Console Check

Test a Page View

Pixel Helper Extension

Quick Start: Common Tracking Patterns

Track a Page View

Track a Product View

Track Add to Cart

Track a Purchase

Identifying Users

Basic Identification

When to Identify

Complete E-commerce Example

Troubleshooting

Pixel Not Firing

Events Not Appearing in Dashboard

Common Mistakes

JavaScript SDK Reference

Standard Events

Properties & Context

Identity Resolution

Custom Events

Connect Destinations

​Installation

​Where to Find Your Pixel ID

​Where to Place the Code

​Standard Websites

​Single Page Applications (SPAs)

​Google Tag Manager

​Verifying Installation

​Browser Console Check

​Test a Page View

​Pixel Helper Extension

​Quick Start: Common Tracking Patterns

​Track a Page View

​Track a Product View

​Track Add to Cart

​Track a Purchase

​Identifying Users

​Basic Identification

​When to Identify

​Complete E-commerce Example

​Troubleshooting

​Pixel Not Firing

​Events Not Appearing in Dashboard

​Common Mistakes

​Related Documentation

JavaScript SDK Reference

Standard Events

Properties & Context

Identity Resolution

Custom Events

Connect Destinations

Installation

Where to Find Your Pixel ID

Where to Place the Code

Standard Websites

Single Page Applications (SPAs)

Google Tag Manager

Verifying Installation

Browser Console Check

Test a Page View

Pixel Helper Extension

Quick Start: Common Tracking Patterns

Track a Page View

Track a Product View

Track Add to Cart

Track a Purchase

Identifying Users

Basic Identification

When to Identify

Complete E-commerce Example

Troubleshooting

Pixel Not Firing

Events Not Appearing in Dashboard

Common Mistakes

Related Documentation