> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upstackdata.com/llms.txt
> Use this file to discover all available pages before exploring further.
# How to Install the Upstack Data Tracking Pixel
> Install the Upstack Data pixel on any website in 5 minutes. Covers installation, verification, common tracking patterns, and identity capture.
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](/guides/shopify/how-to-download-and-install-upstack-data-app-in-shopify) instead.
## Installation
Add this code snippet to every page you want to track, just before the closing `` tag:
```html theme={null}
```
Replace `YOUR_PIXEL_ID` with your actual pixel ID from the [Upstack dashboard](https://app.upstackdata.com). Your pixel ID starts with `px_`.
### Where to Find Your Pixel ID
1. Log in to [app.upstackdata.com](https://app.upstackdata.com)
2. Navigate to **Settings** → **Pixel**
3. Copy your pixel ID (format: `px_abc123def456`)
***
## Where to Place the Code
### Standard Websites
Place the snippet in your site's `` section on every page:
```html theme={null}
My Store
```
### Single Page Applications (SPAs)
For React, Vue, Next.js, or other SPAs:
1. **Add the snippet once** in your main `index.html` or root layout
2. **Track route changes** manually (page views don't fire automatically on navigation)
```javascript theme={null}
// React Router example
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';
function usePageTracking() {
const location = useLocation();
useEffect(() => {
window._upstack('page');
}, [location.pathname]);
}
```
```javascript theme={null}
// 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:
1. Create a new tag with type **Custom HTML**
2. Paste the installation snippet
3. Set trigger to **All Pages** (or your preferred trigger)
4. Publish the container
***
## Verifying Installation
### Browser Console Check
Open your browser's developer console (F12) and run:
```javascript theme={null}
// 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:
```javascript theme={null}
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](/guides/shopify/how-to-install-upstack-data-pixel-helper) Chrome extension for real-time event monitoring without using the console.
***
## Quick Start: Common Tracking Patterns
### Track a Page View
```javascript theme={null}
// 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
```javascript theme={null}
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
```javascript theme={null}
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
```javascript theme={null}
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
```javascript theme={null}
// 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
```javascript theme={null}
// 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:
```javascript theme={null}
// 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
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 ``, not blocked by CSP
Run in console:
```javascript theme={null}
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.
Ensure your pixel ID:
* Starts with `px_`
* Matches exactly what's in your dashboard
* Has no extra spaces or characters
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
Events can take 1-5 minutes to appear in the dashboard. Check the **Live Events** view for real-time data.
Look for outgoing requests after firing an event. You should see a POST request to the tracking endpoint.
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.
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 |
***
## Related Documentation
Full API documentation for all methods and options.
Reference for all standard event types and their properties.
Complete reference for item arrays, customer data, and auto-captured fields.
How user identification enables cross-device tracking.
Create events beyond the standard taxonomy for your needs.
Send events to Meta, Google, TikTok, Klaviyo, and more.