Install

The pinned script tag

One tag for Shopify themes, WordPress, plain HTML and Google Tag Manager, pinned with its integrity hash.

For sites without a build step, the browser part is one <script> tag. It is the same tracker as @parlox/browser, built from the same source, served as an immutable release with its integrity hash.

The tag

Add it to the <head> of every page, with your site's public key:

HTML
<script async src="https://gateway.parlox.io/sdk/1.0.3/parlox.js" integrity="sha384-naJsIFbLpeBsYg6qCN51Tt54BEFhO4MDhTMmrGP4Ja/nXjrfUziCot/3mHbhqCb+" crossorigin="anonymous" data-key="pk_…"></script>

The dashboard's install panel shows this line with your key already filled in.

  • Shopify themes: in the theme's layout/theme.liquid, inside <head>. Checkout pages run no theme code, so add the checkout pixel as well.
  • WordPress: in the theme's <head>, or through a plugin that adds code to it.
  • Plain HTML: in the <head> of each page, or of the template they share.

The tag loads async: nothing on the page waits for it.

Why it is pinned

The address names release 1.0.3, and integrity carries that file's SHA-384 hash. The browser runs exactly that file or nothing: if a single byte served from that address differed, the browser would refuse to run it, even if Parlox's server were compromised. The release loads its recorder from the same release with a hash built into the tag, so pinning the tag pins the whole chain.

Releases are immutable, and each one is listed with its hashes at:

Text
https://gateway.parlox.io/sdk/releases.json

To take a new release, replace the version and the hash in your tag.

Automatic updates instead

If you prefer updates to pinning, this tag always loads the latest release (the file is cached for an hour). It cannot carry an integrity hash, because its content changes:

HTML
<script async src="https://gateway.parlox.io/sdk/parlox.js" data-key="pk_…"></script>

What the tag reads

The tag reads two attributes from its own <script> element, or the same two settings from its URL:

AttributeIn the URLEffect
data-key="pk_…"?key=pk_…The site's public key. Required
data-consent="required"consent=requiredNothing is stored or sent until parlox.consent(true) (Consent)

Nothing else is configurable on the tag. In particular, agent recording cannot be switched off with it; for that, use the npm package with recordAgents: false.

Calls before the tag loads

Because the tag is async, your code can run before it. Put this stub before the tag, and calls to parlox.track and parlox.consent made in the meantime are queued. Once the tag loads, the last consent decision applies, and the track calls replay in order:

HTML
<script>window.parlox=window.parlox||{q:[],track:function(){window.parlox.q.push(['track'].concat([].slice.call(arguments)))},consent:function(g){window.parlox.q.push(['consent',g])}};</script>

parlox.sessionId() exists only once the tag has loaded. The full API: Browser API.

Google Tag Manager

The public repository has a tag template:

  1. Download parlox.tpl.
  2. In Google Tag Manager: Templates → Tag Templates → New → ⋮ → Import, choose the file, save.
  3. Tags → New → Parlox agent analytics, enter the site's public key, set the trigger to All Pages (or to your consent trigger), and publish the container.

Tick Wait for consent if the tag fires on every page and your consent tool calls parlox.consent(true) later. Leave it unticked if the tag already fires only after consent.

The template loads https://gateway.parlox.io/sdk/parlox.js?key=…, the latest release, because Tag Manager's script injection cannot carry an integrity hash. Its permission allows scripts only from https://gateway.parlox.io/sdk/, and the key is checked (^pk_[A-Za-z0-9_-]{3,64}$) and URL-encoded. Where you want the pinned release, paste the tag above into a Custom HTML tag instead.

Ownership

The tag in your homepage's HTML proves you own the domain, with nothing else to do, provided:

  • the homepage is served from the site's own domain (a homepage that redirects to another domain does not count);
  • the tag's src is on gateway.parlox.io and it carries your key in data-key.

A tag added by Google Tag Manager, or with the key only in its URL, is not in the HTML your server sends, so it does not prove ownership. Use the DNS record or the token instead: Verifying the domain.

Size

Release 1.0.3 is 21,990 bytes (about 8.6 kB gzipped). The recorder is 76,505 bytes, and only browsers judged automated download it: never a person's, except one on a virtual machine or a remote desktop judged automated (or, inferred and not tested, one with graphics acceleration turned off), whose recording is masked (Agent recordings).