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 async src="https://app.roasproof.com/js/track.js" data-site="YOUR_SITE_KEY"></script>

“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 _sgnl_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 sgnl() 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
sgnl('track', 'lead', { value: 25, currency: 'EUR' });

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

Call sgnl('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 your consent banner must approve tracking first, add data-consent="required" to the snippet. Events then queue locally and nothing is transmitted until you signal consent:

<script async src="https://app.roasproof.com/js/track.js"
        data-site="YOUR_SITE_KEY" data-consent="required"></script>

// After the visitor accepts your banner:
sgnl('consent', 'grant');

Wire sgnl('consent', 'grant')into your consent-management platform's “accepted” callback.

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 domainon 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
• sgnl('identify') wired into signup/login forms
• Consent gating connected to your banner, if you need it

Next: connect your first destination.