Pixel Service Integration Guide

This page explains how to implement the Rokt Pixel Service to connect conversions with your campaigns. The Pixel Service is intended as a fallback for situations where the Rokt Web SDK is not an option. A common example is advertisers in regulated industries — such as financial services or healthcare — whose security policies enforce a strict Content Security Policy (CSP) that blocks third-party JavaScript execution, but still permits image requests.

Your dedicated Rokt account manager will assist in configuring your account for the Pixel Service. They will provide the required API key and any additional resources needed.

remarque

The instructions below will require development resources to complete. If you need further assistance, please contact your Rokt account manager.

All requests to the Pixel Service are made as HTTP GET requests to:

https://pixels.mparticle.com/v1/{api_key}/Pixel

Where {api_key} is the Rokt API key provided by your account manager.

1. Track Page ViewsLien direct vers 1. Track Page Views

To track a page view, send a pixel request on each page load. Place the request in the <head> of your page, or fire it from your JavaScript as soon as the page loads.

1.1 Enter your Rokt API KeyLien direct vers 1.1 Enter your Rokt API Key

Replace {api_key} in the URL with the Rokt API key provided by your dedicated Rokt account manager.

Your Rokt API Key is a unique credential provided by your Rokt account manager that securely enables your site to connect and interact with the Rokt Pixel Service.

remarque

The Pixel Service is intended for organizations whose Content Security Policy (CSP) blocks third-party JavaScript. If your organization does not have this restriction, use the Rokt Web SDK instead, which provides richer functionality.

1.2 Identify the userLien direct vers 1.2 Identify the user

Rokt requires a consistent user identifier across all pixel calls in a session to stitch together funnel events. Without one, each page view is treated as a separate anonymous user, making it impossible to track funnel progression or build retargeting audiences for users who showed high intent but did not convert.

Pass user identities using comma-separated ui_t (identity type keys) and ui_v (identity type values) parameters.

Known users (email available)

If the user has provided their email address, pass both the session identifier and the email so Rokt can link any earlier anonymous page views to the now-known user:

Un-hashed email: ui_t=other3,email
SHA-256 hashed email: ui_t=other3,other

ui_t=other3,email&ui_v={sessionId},j.smith%40example.com

Anonymous users (no PII available)

If the user has not provided any PII — for example, a user browsing an application funnel without logging in — you must still pass a session-based identifier so Rokt can tie all page view events in that session together.

Generate a unique session ID when the user first arrives and persist it in sessionStorage for the duration of the visit. Pass it on every pixel call using ui_t=other3:

function getSessionId() {
  let sessionId = sessionStorage.getItem('rokt_session_id');
  if (!sessionId) {
    sessionId = crypto.randomUUID();
    sessionStorage.setItem('rokt_session_id', sessionId);
  }
  return sessionId;
}

ui_t=other3&ui_v={sessionId}

remarque

The session ID is not tied to a real user identity — it exists only to group events within a single browsing session. If the user later provides their email (for example, on a conversion confirmation page), include both identifiers so Rokt can associate the session with a known user:

ui_t=other3,email&ui_v={sessionId},j.smith%40example.com

This pattern enables two outcomes for anonymous users who do not convert:

Rokt can see that the user progressed through the funnel (high intent signal).
Rokt places those users into a retargeting audience to re-engage them after the session ends.

1.3 Set user attributesLien direct vers 1.3 Set user attributes

You can include user attributes with each pixel request using comma-separated ua_k (user attribute keys) and ua_v (user attribute values) parameters.

For a list of attributes Rokt recommends collecting, see Recommended user attributes.

ua_k=firstname,lastname,zip&ua_v=Jane,Smith,98103

Page view exampleLien direct vers Page view example

JavaScript
HTML

const API_KEY = "YOUR_API_KEY";
const pixelURL = `https://pixels.mparticle.com/v1/${API_KEY}/Pixel`;
const currentTime = new Date().getTime();

// Generate or retrieve a session ID to tie all page view events together.
// This is required for anonymous users who have not provided an email address.
function getSessionId() {
  let sessionId = sessionStorage.getItem('rokt_session_id');
  if (!sessionId) {
    sessionId = crypto.randomUUID();
    sessionStorage.setItem('rokt_session_id', sessionId);
  }
  return sessionId;
}

// Fetch user email from your persistence layer (e.g., localStorage, sessionStorage, cookies, or server-side session)
// If you're using an un-hashed email address, set it in 'email'.
const email = null; // e.g., localStorage.getItem('userEmail') or null
// If you're using a hashed email address, set it in 'hashedEmail' instead.
// Prior to hashing, lowercase and trim all trailing spaces.
const hashedEmail = null; // e.g., localStorage.getItem('hashedEmail') or null

const sessionId = getSessionId();

const params = new URLSearchParams({
  dt: "ScreenView",
  ct: currentTime,
  hn: window.location.hostname,
  ttl: document.title,
});

if (email) {
  // Known user: pass email and session ID together
  params.append("ui_t", "other3,email");
  params.append("ui_v", `${sessionId},${email}`);
} else if (hashedEmail) {
  // Known user with hashed email: pass hashed email and session ID together
  params.append("ui_t", "other3,other");
  params.append("ui_v", `${sessionId},${hashedEmail}`);
} else {
  // Anonymous user: pass session ID only so Rokt can stitch funnel events together
  params.append("ui_t", "other3");
  params.append("ui_v", sessionId);
}

fetch(pixelURL + "?" + params.toString());

You can also include a 1×1 image pixel for cases where client-side JavaScript is unavailable. The parameter values must be rendered server-side before the page is served to the browser.

<!-- Known user (email available) -->
<img
  src="https://pixels.mparticle.com/v1/{api_key}/Pixel?dt=ScreenView&ct={timestampMs}&hn={hostname}&ttl={pageTitle}&ui_t=other3,email&ui_v={sessionId},{emailAddress}"
  width="1"
  height="1"
/>

<!-- Anonymous user (no PII available) -->
<img
  src="https://pixels.mparticle.com/v1/{api_key}/Pixel?dt=ScreenView&ct={timestampMs}&hn={hostname}&ttl={pageTitle}&ui_t=other3&ui_v={sessionId}"
  width="1"
  height="1"
/>

2. Track ConversionsLien direct vers 2. Track Conversions

To track a conversion, send a pixel request on the page that loads after a customer converts, such as a purchase confirmation or "thank you" page.

When sending the conversion pixel, make sure to:

Include the user's identity (ui_t, ui_v) with their email or hashed email address. If you tracked the user anonymously during their session, pass both the session identifier and the email together so Rokt can link the anonymous funnel activity to the converted user:
```
ui_t=other3,email&ui_v={sessionId},j.smith%40example.com
```
Include user attributes (ua_k, ua_v) with at least:
- firstname
- lastname
- zip
- mobile
Include the following required conversion event attributes (attrs_k, attrs_v):
- conversiontype — The name of the conversion event, e.g., signup or purchase.
- confirmationref — Your transaction or order ID, used as Rokt's deduplication key.

remarque

The conversiontype and confirmationref attributes allow Rokt to optimize your campaign effectively and deduplicate events and conversions appropriately. These are required launch attributes.

When logging a conversion event, include as many user attributes and event attributes as possible to improve Rokt's ability to optimize your campaigns.

JavaScript
HTML

const API_KEY = "YOUR_API_KEY";
const pixelURL = `https://pixels.mparticle.com/v1/${API_KEY}/Pixel`;
const currentTime = new Date().getTime();

// Retrieve the session ID that was used throughout the funnel.
// Passing it alongside the email links the anonymous session to the known user.
function getSessionId() {
  let sessionId = sessionStorage.getItem('rokt_session_id');
  if (!sessionId) {
    sessionId = crypto.randomUUID();
    sessionStorage.setItem('rokt_session_id', sessionId);
  }
  return sessionId;
}

const sessionId = getSessionId();

const params = new URLSearchParams({
  dt: "AppEvent",
  et: "Transaction",
  n: "conversion",
  ct: currentTime,

  // User identity — include both the session ID and email so Rokt can
  // associate the anonymous funnel activity with the now-known user.
  ui_t: "other3,email",
  ui_v: `${sessionId},j.smith@example.com`,

  // User attributes
  ua_k: "firstname,lastname,zip,mobile",
  ua_v: "John,Doe,98103,3125551515",

  // Conversion event attributes — conversiontype and confirmationref are required
  attrs_k: "conversiontype,confirmationref,amount,currency",
  attrs_v: "signup,54321,300.5,USD",
});

fetch(pixelURL + "?" + params.toString());

You can also fire the conversion pixel as a 1×1 image. The parameter values must be rendered server-side before the page is served to the browser.

<img
  src="https://pixels.mparticle.com/v1/{api_key}/Pixel?dt=AppEvent&et=Transaction&n=conversion&ct={timestampMs}&ui_t=other3,email&ui_v={sessionId},{emailAddress}&ua_k=firstname,lastname,zip,mobile&ua_v={firstName},{lastName},{zip},{mobile}&attrs_k=conversiontype,confirmationref,amount,currency&attrs_v={conversionType},{confirmationRef},{amount},{currency}"
  width="1"
  height="1"
/>

Recommended user attributesLien direct vers Recommended user attributes

Rokt recommends setting as many of the following user attributes as possible:

User Attribute Key	Example Value	Notes
firstname	John	The customer's first name.
firstnamesha256	fab1e2e699b3b927cbf875046a64f222	SHA-256 hash of first name. Prior to hashing, lowercase and trim all trailing spaces.
lastname	Doe	The customer's last name.
lastnamesha256	fab1e2e699b3b927cbf875046a64f222	SHA-256 hash of last name. Prior to hashing, lowercase and trim all trailing spaces.
mobile	3125551515	Phone numbers can be formatted either as `1112345678` or `+1 (222) 345-6789`.
mobilesha256	fab1e2e699b3b927cbf875046a64f222	SHA-256 of mobile number. Prior to hashing, format as `5551234567` (no dashes or spaces).
age	33	The customer's age.
dob	19900717	Date of birth. Formatted as `yyyymmdd`.
gender	M	The customer's gender. For example, `M`, `Male`, `F`, or `Female`.
city	Brooklyn	The customer's city.
state	NY	The customer's state.
zip	11201	The customer's zip code.
title	Mr	The customer's title. For example, `Mr`, `Mrs`, `Ms`.
language	en	Language associated with the purchase.
value	52.25	The value of the customer.
predictedltv	136.23	The total predicted lifetime value of the customer.

All user attributes must have distinct names.

3. Test Your IntegrationLien direct vers 3. Test Your Integration

Rokt recommends testing your integration to ensure that pixel requests are sent correctly and that events are logged successfully.

remarque

After verifying the following steps, perform a few test purchases or sign-ups as an end user. Then, provide the email or hashed email you used to your Rokt account manager so they can verify that the data is ingested properly into Rokt.

Testing Page View TrackingLien direct vers Testing Page View Tracking

Open a new browser window.
Access your browser's developer tools panel. For most browsers, do this by right-clicking on your screen and selecting Inspect.
In the developer tools panel, navigate to the Network tab and enter pixels.mparticle.com into the filter bar.
Load the page where you placed the page view pixel. You should see a GET request to pixels.mparticle.com.

Testing Conversion TrackingLien direct vers Testing Conversion Tracking

Open a new browser window.
Access your browser's developer tools panel. For most browsers, do this by right-clicking on your screen and selecting Inspect.
In the developer tools panel, navigate to the Network tab and enter pixels.mparticle.com into the filter bar.
Complete a test conversion on your site. On the confirmation page, you should see a GET request to pixels.mparticle.com containing your conversion event attributes.

TroubleshootingLien direct vers Troubleshooting

While testing, check that:

The dt parameter is set correctly (ScreenView for page views, AppEvent for conversion events).
The ct parameter contains a valid epoch timestamp in milliseconds.
All query parameter values are URL-encoded, especially email addresses (e.g., %40 for @).