Pixel SDK

The Pruuv Pixel is a small script for your website (about 16 KB, or 6 KB compressed). It saves the ad click IDs and UTM tags a visitor arrives with, records page views, and links the visitor to their email when they fill in a form. Pruuv uses this to match your leads to the ads that brought them, and to send better-matched conversions back to the ad platforms.

Quick start

1. Add the tag to every page

Copy the tag from Settings → Pixel SDK in Pruuv. It already contains your site key. Only agency users can open this page. If it shows Enable web pixel, an agency admin must click it first. If you cannot open the page, ask your Pruuv contact for the tag. Paste the tag just before the closing </body> tag on every page, and always on the landing pages your ads link to:

<script async src="https://ai.pruuv.com/pixel.min.js"
        data-site-key="YOUR_SITE_KEY"
        onload="Pruuv.page()"></script>

• data-site-key is your site key. It is public, so it is safe in your page.
• onload="Pruuv.page()" records a page view once the script has loaded. The script is async, so Pruuv does not exist before then. Remove the attribute if you do not want page views.
• Load the script from https://ai.pruuv.com. The pixel sends its data to the host it was loaded from.

If your Content-Security-Policy blocks inline code, load the pixel from your own script file instead. Your policy must allow https://ai.pruuv.com in both script-src and connect-src.

var script = document.createElement('script');
script.src = 'https://ai.pruuv.com/pixel.min.js';
script.async = true;
script.dataset.siteKey = 'YOUR_SITE_KEY';
script.onload = function () { window.Pruuv.page(); };
document.head.appendChild(script);

2. List your domains

In Settings → Pixel SDK (agency admins only), add every domain the tag runs on under Allowed domains (one per line), then click Save domains. A domain also covers its subdomains: example.com allows www.example.com and apply.example.com. The same list applies to track().

3. Identify the visitor

Call Pruuv.identify() as soon as you know the visitor’s email, usually in your form’s submit handler. The first argument must be the email. If you know your CRM’s ID for this lead, pass it as reference.

Pruuv.identify('jane@example.com', {
  reference: 'crm-contact-12345', // your CRM's ID for this lead (recommended)
  phone:     '+441234567890'      // optional: used by later track() calls
});

• Call it before your CRM sends the lead to Pruuv, so the click IDs are ready when the lead arrives. Do not wait for your CRM’s reply.
• The lead your CRM sends must carry the same email, the same reference or the visitor ID. That is how Pruuv links them: see How Pruuv links the pixel to your CRM.
• It needs the site key. Without one, it logs a warning and sends nothing.

4. Send the conversion from the browser (optional)

You only need this when your CRM does not send the lead to Pruuv. Call Pruuv.track() when the conversion happens, for example after your form is sent:

Pruuv.track('YOUR_STAGE_ID', 'YOUR_STAGE_TOKEN', {
  reference: 'crm-contact-12345',
  value:     250,
  currency:  'GBP'
});

Each funnel stage has its own stage ID and token. To report a later stage, call track() again with that stage’s pair.

Where to find your keys

Tag settings

Set these as attributes on the tag, or in window.PruuvConfig before the script loads. When both set a value, the tag attribute wins. For consent mode, either one turns it on. Add the tag only once per page.

<script>
  window.PruuvConfig = { siteKey: 'YOUR_SITE_KEY', requireConsent: true };
</script>
<script async src="https://ai.pruuv.com/pixel.min.js"></script>

API reference

The script adds one object, window.Pruuv, with seven methods. It only exists once the script has loaded, so write window.Pruuv?.identify(…) in code that might run earlier. The methods catch network errors and never report the server’s answer, so check it in the Network tab (see Troubleshooting).

Pruuv.page()

Records a page view. It takes no arguments and needs the site key. In a single-page app, call it after each route change (see Single-page apps). Each call sends:

Page views go to /api/pixel/collect. Pruuv uses them for the checks in Data Health → Pixel. For visitors you identify, it also uses them to fill in the click IDs, browser details, location and page URL their leads are missing. Page views themselves are never sent to the ad platforms.

Pruuv.identify(email, options)

identify() sends the email hash, the reference and the event ID, together with the click IDs saved in this browser, the first-touch data and the browser’s user agent. Pruuv adds the IP address and approximate location. It keeps one record per visitor ID (the _pruuv_vid cookie): a later call updates the values it carries, but never clears a click ID saved earlier.

It also saves the email and options in the _pruuv_identity cookie, so later track() calls can use them. It returns nothing, so do not await it. Call it once per form, not on every page.

Pruuv.track(stageId, token, options)

Along with your options, track() sends the saved UTM tags (including utm_matchtype), the click IDs and click time, the first-touch data when it differs, the browser’s user agent, and the page URL without its query string (event_source_url). It also sends identity_user_id: the reference given to identify(), or the email when there was no reference.

How the reference is chosen. track() uses the first of these that is set: options.reference → options.order_id → the reference given to identify() → the email given to identify() → pruuv_<timestamp>.

Duplicates. Pruuv keeps one event per stage and reference (and item_reference, when set). This is permanent, not a time window. A repeat call returns duplicate: true. It never creates a second event. It sends nothing itself, and never re-sends a conversion that was already sent. It only fills in fields the stored event is missing, such as a click ID, email hash, browser details, value or currency. It never adds UTM tags, so it cannot get the event matched to an ad. If the event has not been sent yet, the new fields go with it when it is. Give each real conversion its own reference, or use item_reference for a second order from the same person.

Responses. track() posts to /api/webhooks/funnel/{stageId}. The pixel does not read the answer, so check it in the Network tab or in Data Health → Live:

Pruuv.visitorId()

Returns the visitor ID, the value of the _pruuv_vid cookie, and creates the cookie if it does not exist yet. It creates no other cookie. It returns null before consent (in consent mode), for a bot, and on a page that is not served over https, where the browser cannot make the ID.

Put it in a hidden field of your form, and have your CRM send it with the lead as pruuv_visitor_id (see Webhook API). Pruuv then finds this browser’s click IDs even when the lead’s email differs from the one identify() saw.

Pruuv.consent(), Pruuv.optOut() and Pruuv.reset()

Examples

A form whose leads your CRM sends to Pruuv

<form id="lead-form">
  <input name="email" type="email" required>
  <button type="submit">Get a quote</button>
</form>

<script>
  document.getElementById('lead-form').addEventListener('submit', function () {
    var email = this.querySelector('[name="email"]').value;
    // Your CRM sends this lead to Pruuv with the same email
    if (window.Pruuv) window.Pruuv.identify(email);
  });
</script>

If the page knows your CRM’s ID for the lead, pass it too: identify(email, { reference: leadId }).

A form that also reports the conversion

async function handleSubmit(data) {
  window.Pruuv?.identify(data.email, { reference: data.leadId });

  const result = await submitForm(data);
  if (result.ok) {
    window.Pruuv?.track('YOUR_STAGE_ID', 'YOUR_STAGE_TOKEN', {
      reference: data.leadId,
      value:     250,
      currency:  'GBP'
    });
  }
}

Stop Meta and TikTok counting an event twice

If you also run the Meta pixel (or the TikTok pixel) and fire an event on your site, the platform gets it twice: once from your pixel and once from Pruuv. Give both the same event ID and the platform keeps only one (Meta’s guide, TikTok’s guide):

function handleSubmit(email) {
  var eventId = 'lead-' + crypto.randomUUID();
  fbq('track', 'Lead', {}, { eventID: eventId });
  window.Pruuv?.identify(email, { event_id: eventId });
}

• The event names must match too. The platform only merges two events with the same event ID and the same name. Your pixel’s event (Lead above) must be the event that stage is mapped to in Pruuv.
• Use a new event ID for every event. identify() carries the ID of the lead itself (your first stage). For a later event, such as a signature, fire your pixel with a new ID and send that ID with the same event: Pruuv.track(stageId, token, { event_id: eventId }), or event_id in your CRM’s webhook post for that stage.
• One ID belongs to one lead. If the same ID reaches Pruuv on several events, only the earliest one sends it. The others go with Pruuv’s own ID.
• Claims and other items. If your site fires one event per claim with the claim number as its event ID, set that destination’s Event ID to Item reference in Pruuv. Pruuv then sends each event’s item_reference as the event ID. The text must be exactly the same. Two stages that use Item reference on one ad account need different event names.
• Send the ID before Pruuv sends the event. The platform merges the two only within 48 hours, and Pruuv can only use an event ID that reaches it before the event is sent. So call identify() in the submit handler, or send event_id in the same request as the event.
• Pruuv never creates an event ID for you. Without one, events go with Pruuv’s own ID, as before.

Single-page apps

A route change inside a single-page app does not reload the page, so the tag’s onload fires only once. Call Pruuv.page() from your router after each route change. The pixel already re-reads the URL for UTM tags and click IDs on pushState, replaceState, popstate and hashchange. For the Next.js App Router:

'use client'

import { usePathname, useSearchParams } from 'next/navigation'
import { useEffect, useRef } from 'react'

export function usePruuvPageViews() {
  const pathname = usePathname()
  const searchParams = useSearchParams()
  const isFirstPage = useRef(true)

  useEffect(() => {
    // The tag's onload already recorded the first page
    if (isFirstPage.current) {
      isFirstPage.current = false
      return
    }
    window.Pruuv?.page()
  }, [pathname, searchParams])
}

Google Tag Manager

Paste the tag, exactly as copied from Pruuv, into a Custom HTML tag that fires on all pages. Then add a second Custom HTML tag for identify(), fired by your form-submit trigger:

<script>
  if (window.Pruuv) {
    window.Pruuv.identify('{{DLV - email}}', { reference: '{{DLV - lead_id}}' });
  }
</script>

How Pruuv links the pixel to your CRM

1. A visitor clicks an ad and lands on your site. The pixel saves the click IDs.
2. They fill in your form. identify() sends their email hash and your reference to Pruuv, with the click IDs.
3. Your CRM sends the lead to Pruuv with the same email or reference, and with the lead’s UTM tags (see Webhook API).
4. When the lead carries a visitor ID (pruuv_visitor_id, see Pruuv.visitorId()), Pruuv tries that browser first. It skips the browser if it was last identified with another email, as on a shared computer. Then Pruuv finds the visitor by email hash, then by reference. It adds the click IDs, browser details and location the lead is missing. It never overwrites what your CRM sent.

This also works across devices. If the visitor clicked the ad on their phone and identify() ran there, a lead with the same email gets the phone’s click ID.

Pruuv does this when the lead arrives, and again every 30 minutes for leads up to 7 days old. So a late identify() still counts, if the lead has the same email, the same reference in lowercase, or the browser’s visitor ID. But Meta and TikTok may already have received the conversion without the click ID, which gives a weaker match. Call identify() first.

What the pixel saves from the URL

On every page load, and on every route change inside the page, the pixel reads the URL. It saves the UTM tags utm_source, utm_medium, utm_campaign, utm_content, utm_term and utm_matchtype, and sends them with track() calls (see Attribution). It does not add them to the leads your CRM sends. It also saves these click IDs:

Click IDs are only in the URL of the first page after the ad click. So the tag must be on your landing pages, not only on the thank-you page.

First touch and last touch

Conversions use the last touch. The first touch is stored with the event.

Cookies

All cookies are first-party. The pixel sets them with JavaScript on the page’s own host (with no Domain attribute), with path=/ and SameSite=Lax.

_pruuv_vid, _pruuv_sid and _fbp are created by the first page(), identify() or track() call, not when the script loads. visitorId() creates _pruuv_vid only.

Saved copies in localStorage

The pixel also saves a copy of _pruuv_session, _pruuv_first_touch, _pruuv_vid, _fbp and _fbc in the browser’s localStorage, under keys that start with _pruuv_mirror.. Each copy has the same expiry as its cookie. When one of those cookies is missing on page load and its copy has not expired, the pixel writes the cookie back from the copy, keeping the original expiry.

This keeps click IDs for visitors who convert a few days after the click. Safari deletes localStorage only after 7 days pass with no visit to the site, so each visit restarts that clock. A visitor who comes back after a longer gap has no saved click IDs.

• A cookie that exists always wins. If Meta’s own pixel has written a newer _fbc or _fbp, the copy is updated to match it.
• The copies are written and restored only when consent allows, and optOut() deletes them.
• _pruuv_identity, _pruuv_sid and _pruuv_consent are never copied.

Cookies and localStorage both belong to one host. Data saved on www.example.com is not visible on apply.example.com, so a visitor who lands on one host and converts on another has no click IDs on the second.

Consent mode

By default the pixel does not wait for consent: it writes cookies and sends calls straight away. The tag you copy from Pruuv does not turn consent mode on. If the browser sends Do Not Track, the pixel writes no cookies and sends nothing, even after consent(true).

To wait for consent, add data-consent="required" to the tag (or set requireConsent: true). Then:

• Nothing is written or sent until you call Pruuv.consent(true). Until then, the page’s click data and any page(), identify() and track() calls wait in memory.
• If the visitor opens another page before accepting, the waiting data is lost, including the landing page’s click IDs.
• The choice is saved in _pruuv_consent for 90 days and applies to later pages.

// The visitor accepts
Pruuv.consent(true);

// The visitor declines
Pruuv.consent(false);

// The visitor withdraws consent later: this also deletes the pixel's cookies
Pruuv.optOut();

Security and limits

• The site key is public. Your Allowed domains list is what stops other websites from using it.
• A track() call from a browser must carry the stage token and come from an allowed domain. The token is visible in your page, so the domain list is the real protection.
• Requests from a server (with no Origin header) need no token: see Webhook API → Authentication. Keep your stage IDs private.
• Rotate site key (in Settings → Pixel SDK, agency admins only) stops page() and identify() at once on every tag that uses the old key. Update your tags straight after. It does not stop track(), which uses the stage token. To stop a stage’s browser track() calls, an agency admin can click Rotate secret on that stage. Server posts need no token, so they keep working.
• Disable pixel (agency admins only) stops page views, identify() calls and browser track() calls.
• Each site key and each stage can receive 1,000,000 requests an hour. This is a safety limit, not a quota you should expect to reach.

Privacy

• identify() and track() hash the email and phone (SHA-256) in the browser before sending them.
• The _pruuv_identity cookie keeps the email and identify() options in plain text in the visitor’s browser for up to 90 days. Other scripts on your page can read it.
• If you pass no reference, the email becomes the event’s reference and is sent and stored in plain text. Pass a reference to avoid this.
• Other fields you pass to track() are sent as you give them. Pruuv hashes the personal fields it knows (see Webhook API), but keeps a copy of each request.
• Page views store the visitor’s IP address, user agent, approximate location and the full page URL, including its query string. Do not put personal data in your URLs.
• The pixel only talks to Pruuv. It loads no other scripts and sets only first-party cookies. Pruuv sends a conversion only to the connected ad account the lead was matched to (see Conversion sending).

Browser support

• The page must use HTTPS (or run on localhost). On plain HTTP, browsers block the crypto functions the pixel needs, so nothing is sent.
• It needs a recent browser. It uses crypto.randomUUID(), which arrived in Chrome and Edge 92, Firefox 95 and Safari 15.4.
• It ignores bots and automated browsers. Playwright, Puppeteer and Selenium set navigator.webdriver, so nothing is sent from them. Test in a normal browser window.

Troubleshooting

Check the requests

Open your browser’s developer tools, go to the Network tab and load the page. Look for these requests to https://ai.pruuv.com:

Errors from page views and identify():

For track() errors, see the responses under Pruuv.track().

No request at all

• The Console shows [Pruuv] siteKey is required for page() (or for identify()): the tag has no data-site-key.
• The Console shows [Pruuv] stageId and token are required for track(): an argument is missing.
• The Console shows Pruuv is not defined: the call ran before the script loaded, or the script did not load. Use window.Pruuv?. and check the script URL.
• The browser has Do Not Track turned on, or the visitor declined consent.
• Consent mode is on and Pruuv.consent(true) has not been called yet.
• The browser is automated, or looks like a bot.
• The page uses plain HTTP. The Console shows an error about randomUUID or digest.

Check in Pruuv

• Data Health → Pixel shows when each site last sent a page view, and how many CRM leads were linked to an identify() call.
• Data Health → Live shows track() requests as they arrive, including most rejected ones (wrong token, domain not allowed, invalid body).
• Page-view and identify() errors are not shown in Pruuv. Use the Network tab.

Leads arrive without click IDs

• The tag must be on the landing pages your ads link to.
• Call identify() on every form, before your CRM sends the lead, and make sure the lead carries the same email or reference.
• The visitor moved to another host (cookies belong to one host), or came back after Safari removed the cookies.
• In consent mode, the visitor opened another page before accepting.

Low Meta match rate

• Call identify() before your CRM sends the lead, so the lead gets the fbc, fbp, IP address and user agent.
• Send the phone number with each lead: from your CRM, or in track(). Use E.164 format.
• Make sure the tag is on your landing pages, so fbclid is saved as _fbc.