Setup Pixel - UserPath Documentation

Get UserPath tracking up and running on your website or application in just a few minutes. Choose the integration method that best fits your setup.

Quick Start

Most users can get tracking working in under 5 minutes using our browser pixel. Advanced users can integrate UserPath directly into their application code for maximum control.

Installation Methods

UserPath offers multiple ways to integrate tracking into your application:

Choose Your Integration Method

Pick the method that best fits your technical setup and requirements

Feature	Basic	Advanced
Setup time	Browser Pixel 2 minutes	JavaScript SDK 5 minutes
Technical requirements	Just add one script tag	Node.js knowledge required
Customization	Data attributes & config	Full programmatic control
Event tracking	Auto-tracking + manual events	Fully customizable tracking
Server-side tracking	Via direct HTTP API calls	Built-in server SDK support
First-party integration	Nginx/Apache proxy	Node.js backend integration

Method 1: Browser Pixel (Quickest)

The fastest way to get started. Just add a script tag to your website - UserPath automatically tracks page views, clicks, forms, errors, and performance metrics.

Browser Pixel Integration

Simple script tag integration for immediate tracking

Custom Properties

We only support primitive custom properties. No arrays, objects, or complex types.

Agnostic First-Party Setup

Route tracking through your own domain to bypass ad-blockers and privacy browsers, ensuring complete data collection and richer analytics using an framework agnostic approach:

First-Party Pixel Setup

Bypass ad-blockers and maximize data collection by routing through your own domain

First-Party Geolocation

Currently, UserPath only supports Cloudflare geolocation headers. If your server is not within the Cloudflare network, you will need to manually mimic and forward the geolocation headers to UserPath.

Method 2: JavaScript SDK (More Control)

For full programmatic control and advanced features. The UserPath SDK works in both browser and Node.js environments.

NPM Package Installation

Install UserPath SDK for browser or server-side tracking

Node.js First-Party Setup

Alternatively, you can also route UserPath tracking through your backend using the UserPath SDK for node:

First-Party SDK Setup

Route tracking through your own backend to bypass ad-blockers and ensure complete data collection

Enabling Cloudflare Headers

When using a first-party implementation, if your server is within the Cloudflare network, and you are still not seeing geolocation data, please check if you have enabled the Cloudflare headers in your UserPath configuration.

Here's how to enable and use these headers:

Enable Geolocation:

Log in to your Cloudflare dashboard and select the relevant domain.
Go to Rules > Settings in the Cloudflare sidebar.
Select the Managed Transforms tab.
Toggle to enable the Add visitor location headers transform.

Access the Headers:

Once enabled, Cloudflare will automatically add the geolocation headers to incoming requests.
You can access these headers within your application's code or server-side logic and forward them to UserPath.
If you are using the UserPath SDK for node, we will automatically handle the headers for you.

Available Cloudflare Geolocation Headers

Headers automatically added by Cloudflare when IP Geolocation is enabled

header	description	example
CF-IPCountry	Two-letter country code	US,GB,CA
CF-IPCity	City name	New York,London,Toronto
CF-IPContinent	Continent code	NA,EU,AS
CF-IPLatitude	Latitude coordinate	40.7128
CF-IPLongitude	Longitude coordinate	-74.0060
CF-IPPostalCode	Postal code	10001
CF-IPMetroCode	Metro code	501
CF-IPRegion	Region name	California,Ontario
CF-IPRegionCode	Region code	CA,ON
CF-IPTimezone	Timezone	America/New_York
CF-IPASN	Autonomous System Number	AS15169

Important

Running UserPath as a first-party implementation is the best way to get the most data, and it doesn't require a paid Cloudflare plan. We highly recommend it.

Common Issues

Failing to instantiate a new UserPath instance

Uncaught Error: Failed to construct 'URL': Invalid URL

UserPath sets a cookie to track the session ID. In order to set the cookie, it needs to be able to construct a full URL. Make sure that the serverUrl is a valid URL.

Example:

Don't

Organization ID is required

If you are unable to send events to UserPath, it is likely because the app id being sent is invalid. Check if the correct app id is being initialized in the UserPath instance.

Example:

Don't