Install the tracking script

The tracking script is the capture half of RoasProof: it records the ad click, the visitor and their sessions first-party on your domain, so the conversion that happens days later can be matched back to the click that caused it. This article covers installation, what is captured automatically, the JavaScript API, consent gating and serving the script from your own domain.

The snippet

Add the snippet to every page of your site, just before the closing </head> tag. Your ready-made snippet, with the site key filled in, is on the Setup & API keys page:

<script>window.rpq=window.rpq||(function(){var f=function(){f.q.push(arguments)};f.q=[];return f}());</script>
<script async src="https://app.roasproof.com/js/track.js" data-site="YOUR_SITE_KEY"></script>

Paste both lines, in that order. The first defines rpq() straight away, so a call you make further down the page is queued and replayed once the script arrives, instead of failing because the script had not loaded yet. The second loads the script itself.

“Every page” includes landing pages, the checkout and thank-you pages: the pages where clicks land and conversions complete are exactly the ones that matter. The script loads asynchronously and does not block rendering.

The site key ties data to the right website in your workspace. Data is only accepted from the origins you listed as allowed domains on the website. If events from a checkout subdomain are missing, add that subdomain to the list.

What is captured automatically

• Page views, link clicks and form submits: no extra code required.
• Click IDs and campaign data on first touch: fbclid, gclid, ttclid, UTM parameters, the referrer and the landing path are read from the landing URL and stored first-party, tied to a persistent visitor ID.
• The Meta _fbp / _fbc cookies: captured so server-side events can carry them even after the browser copy is gone.

The visitor ID lives in the _rp_vid cookie. Your backend passes this value with server-side orders so the stored browser identifiers are merged into the outgoing conversion. See Send orders and events from your backend.

The JavaScript API

The snippet exposes a global rpq() function for the two things worth doing manually (firing conversions in the browser and attaching an identity to the visitor):

// Fire a conversion event from the page
rpq('track', 'lead', { value: 25, currency: 'EUR' });

// Attach an email to the visitor (stored SHA-256 hashed)
rpq('identify', { email: '[email protected]' });

Call rpq('identify') wherever you learn who the visitor is: signup forms, newsletter opt-ins, login. The email is hashed before storage and joins the anonymous click history to a real person, which is what makes cross-device and multi-week attribution work.

Consent gating

If a cookie banner has to approve tracking first, the cleanest setup is to not load the script until it does. Keep the first line of the snippet, drop the second, and inject the script from your banner's “accepted” handler:

<script>window.rpq=window.rpq||(function(){var f=function(){f.q.push(arguments)};f.q=[];return f}());</script>

<script>
function loadRoasProof() {
  var s = document.createElement('script');
  s.async = true;
  s.src = 'https://app.roasproof.com/js/track.js';
  s.setAttribute('data-site', 'YOUR_SITE_KEY');
  document.head.appendChild(s);
}
// call loadRoasProof() once the visitor accepts
</script>

A visitor who declines, or who never answers, then makes no request to us at all: no cookies, no local storage, and no request that would reveal their IP address and user agent. On WooCommerce our plugin does exactly this for you, driven by the WP Consent API, so any compatible banner works with no configuration.

The script has no consent switch of its own, on purpose. Not loading it is the gate, and it is a stronger one than any setting inside the script could be. Two consequences worth knowing: a visitor who browses several pages before accepting has already lost the click ID with the landing URL, since nothing was stored to carry it forward; and withdrawing consent takes effect on the next page view, because a script that is already running cannot be unloaded.

First-party tracking domain (recommended)

By default the script is served from app.roasproof.com. On Growth plans and above you can serve it from a subdomain you own (t.mystore.com) so the script and its data requests are same-site and generic third-party blocklists never match them.

Set the custom domain on the website's settings, point a CNAME record at us, and DNS and SSL are verified and renewed automatically. Then swap the snippet's src to your domain. The features page explains why this materially reduces losses.

Checklist before moving on

• Snippet on every page, including checkout and thank-you pages
• All sending origins listed in allowed domains
• rpq('identify') wired into signup/login forms
• Consent gating connected to your banner, if you need it

Next: connect your first destination.