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:

<script>
window._upstack = window._upstack || function() {
  (window._upsqueue = window._upsqueue || []).push(arguments);
};
_upstack('init', 'YOUR_PIXEL_ID');
</script>
<script async src="https://prod2-cdn.upstackified.com/scripts/px/ups.min.js"></script>

Replace YOUR_PIXEL_ID with your actual pixel ID from the Upstack dashboard. Your pixel ID starts with px_.

Where to Find Your Pixel ID

Log in to app.upstackdata.com
Navigate to Settings → Pixel
Copy your pixel ID (format: px_abc123def456)

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>
  
  <!-- Upstack Pixel — add before </head> -->
  <script>
  window._upstack = window._upstack || function() {
    (window._upsqueue = window._upsqueue || []).push(arguments);
  };
  _upstack('init', 'px_your_pixel_id');
  </script>
  <script async src="https://prod2-cdn.upstackified.com/scripts/px/ups.min.js"></script>
</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)

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

function usePageTracking() {
  const location = useLocation();
  
  useEffect(() => {
    window._upstack('page');
  }, [location.pathname]);
}

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

export function Analytics() {
  const pathname = usePathname();

  useEffect(() => {
    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', {
  content_ids: ['PRODUCT_123'],
  content_name: 'Blue Running Shoes',
  content_type: 'product',
  value: 89.99,
  currency: 'USD'
});

Track Add to Cart

window._upstack('track', 'add_to_cart', {
  content_ids: ['PRODUCT_123'],
  content_name: 'Blue Running Shoes',
  content_type: 'product',
  value: 89.99,
  currency: 'USD',
  num_items: 1
});

Track a Purchase

window._upstack('track', 'purchase', {
  content_ids: ['PRODUCT_123', 'PRODUCT_456'],
  value: 149.99,
  currency: 'USD',
  order_id: 'ORDER_789',
  num_items: 2
});

Always include order_id for purchase events — it’s used for deduplication across browser and server events.

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 (on every page load)
window._upstack('page');

// 2. Product view (on product page)
window._upstack('track', 'view_content', {
  content_ids: ['SKU-001'],
  content_name: 'Premium Widget',
  content_type: 'product',
  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', {
    content_ids: ['SKU-001'],
    content_name: 'Premium Widget',
    content_type: 'product',
    value: 49.99,
    currency: 'USD',
    num_items: 1
  });
});

// 4. Begin checkout (on checkout page)
window._upstack('track', 'initiate_checkout', {
  content_ids: ['SKU-001'],
  value: 49.99,
  currency: 'USD',
  num_items: 1
});

// 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', {
  content_ids: ['SKU-001'],
  value: 49.99,
  currency: 'USD',
  order_id: 'ORD-12345',
  num_items: 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:

Starts with px_
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 1-5 minutes to appear in the dashboard. Check the Live Events view 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 `order_id` on purchases	Include 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.

​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