Tracker reference

The tracker is a small script served for each website at https://pixelrelay.co/api/tracker/{API_KEY}.js. It defines one global object, window.PixelRelayTracker, queues events and posts them to the website's track endpoint in batches.

Loading and starting#

<script>
  window.PixelRelayTrackerConfig = { autoTrackPageViews: true };
</script>
<script src="https://pixelrelay.co/api/tracker/YOUR_API_KEY.js" async></script>

When the script loads and finds window.PixelRelayTrackerConfig, it calls PixelRelayTracker.init() with it. Without the config object nothing starts on its own: call PixelRelayTracker.init({...}) yourself once the script has loaded.

The script is cached for an hour. A paused website, or an unknown key, gets a 404 instead.

Options#

The queue is also sent when the visitor leaves the page or switches tab, with keepalive, so the last event is not lost. If a send fails, the events are put back in the queue and tried again.

Methods#

track(eventName, customData, userData)#

Queue one event. eventName is your own name, matched against the website's mappings. customData holds the event's details and userData the visitor's details; both are optional. See Send events for the fields the relay keeps.

PixelRelayTracker.track('schedule_appointment', { value: 150, currency: 'GBP' }, { email: 'person@example.com' });

Helpers#

Note the argument order of trackLead: the visitor's details come first.

flush()#

Send the queue now. Useful right before your own code navigates away.

init(options)#

Start the tracker with options. Runs once; later calls are ignored.

What the tracker adds by itself#

Each event carries the time, a unique event ID (Meta uses it to drop duplicates), the page address and the referring page. The visitor details always get the browser's user agent and, when present, Meta's _fbp and _fbc cookies, or a click ID built from fbclid in the address. The relay then cleans all of it, see What the relay removes.

Single-page apps#

autoTrackPageViews sends one page view per page load. In a single-page app, call PixelRelayTracker.trackPageView() after each route change.