Verimetriq
Sign in
All documentation

Integration guide

This guide walks a developer through connecting a website to Verimetriq’s data layer: install the collector, capture events, identify people, and feed revenue so ROAS and customer journeys work. It takes about ten minutes.

What the data layer is. Verimetriq keeps its own visitor_id (a first‑party cookie) as the key of every customer journey, and captures Google/Facebook identifiers, gclid/fbclid and UTM tags as attributes. Because the journey is not keyed on _ga/_fbp — cookies that rotate and get cleared — it survives a GA client_id reset and spans devices.

1. Get your tracking key

In the panel, open Settings → Data layer. Each organisation has its own key (it looks like vmq_…). Press + New key if there is none yet.

The key is public by design — it ships in your page source, exactly like a Google Analytics measurement ID. If a key ever leaks, revoke it in the same screen and issue a new one; the old one stops being accepted within seconds.

2. Add the snippet

Paste this just before </head> (or anywhere in the page). Use the snippet shown in Settings → Data layer — it already carries your key:

<script async
  src="https://<your-collector-domain>/api/collect/script"
  data-key="vmq_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"></script>

That is all that is required. On load the collector:

  • creates or reads the first‑party visitor_id (cookie _vmq_id, kept ~400 days, mirrored to localStorage),
  • sends a pageview event,
  • captures _ga, _fbp, _fbc, gclid, fbclid, the vmq campaign token and all utm_* parameters as attributes of that event.

The snippet is ~1.5 KB, vanilla JavaScript, and loads asynchronously — it does not block rendering.

By default the snippet loads from Verimetriq’s host, which makes it a third‑party request — Safari’s ITP and ad‑blockers clip third‑party tracking. To collect as first‑party, point a subdomain of your own site at the collector:

  1. In Settings → Data layer, set Custom event domain to e.g. t.yoursite.com and save.

  2. Add the DNS record shown there:

    t.yoursite.com   CNAME   <verimetriq-collector-host>

  3. Once DNS propagates and the TLS certificate is issued, events flow through your domain. The snippet retargets automatically — no code change on your side; the collector derives its endpoint from the script’s own origin.

Until the CNAME is live, tracking keeps working from Verimetriq’s host.

4. The vmq() API

The snippet defines a global window.vmq(command, …).

Custom events

vmq('event', 'signup_click');
vmq('event', 'add_to_cart', { product: 'SKU-42', price: 1990 });

The second argument is a free‑form props object (kept if it serialises under 4 KB).

Identify a person (identity stitching)

Call identify the moment you know who the visitor is — on login, a submitted lead form, or checkout:

vmq('identify', { email: 'anna@example.com' });
vmq('identify', { phone: '+380671112233' });

This links the current visitor_id to the person. The email or phone is sent to the collector over TLS and hashed immediately on receipt (HMAC, keyed per organisation); Verimetriq stores only the hash and never persists or logs the raw value. Every device the person uses is then merged into one journey. If you prefer the raw value never to leave the browser at all, send a pre‑computed identifier instead (see below).

Pre‑computed identifier (no PII leaves the browser). If you already have a stable pseudonymous id for the user — a Keycloak sub, your own user id, or a hash you compute yourself — pass it as id. Nothing reversible is sent:

vmq('identify', { id: user.sub }); // e.g. Keycloak subject

Verimetriq treats it as one more identity handle (hashed like the rest), so a person is stitched across devices without an email or phone ever being transmitted.

Revenue → ROAS

On the thank‑you page, emit a purchase with its value. This is what fills the ROAS column for campaigns:

vmq('event', 'purchase', { value: 1990, currency: 'UAH' });

Revenue is credited to the person who clicked a campaign link — even if they clicked on a phone and bought on a laptop.

Add data-consent="strict" to the snippet to hold every event in a queue until the visitor agrees. After your cookie banner’s Accept, call:

vmq('consent'); // flushes the queued pageview and lets later events through

With strict mode, nothing is sent — not even the pageview — until consent is given. Verimetriq’s own marketing site uses exactly this pattern.

6. What ends up where

You callVerimetriq records
page loadpageview + _ga/_fbp/gclid/fbclid/UTM as attributes
vmq('event', name, props)a named event with your props
vmq('identify', {email|phone})visitor ↔ person link (hash only)
vmq('event','purchase',{value})revenue for attribution & ROAS

Find a person’s whole path in Settings → Data layer → Customer journey (search by email or phone); campaign clicks, revenue and ROAS live under Campaigns.

Next

Stuck? Write to support@verimetriq.com — a person answers.