Skip to content
Lapis
Esc
↑↓navigate↵open⌘Jpreview
On this page

Self-hosting the pixel

Serve the Lapis pixel from your own site: download a pinned version, verify it, and decide when it updates.

By default you load the pixel from the Lapis CDN and it stays up to date on its own. If you would rather serve the file from your own site and decide when it changes, for example for a security review or a strict Content Security Policy, you can host a pinned version yourself.

Standard CDN tag Self-hosted
Script host cdn.trylapis.com Your own site
Updates Automatic When you choose
Consent gate for EU and UK visitors Applied by Lapis from the visitor’s location Yours to apply (see step 4)
Pixel version v2.0 v2.2.1

Note: Self-hosted builds are pinned versions. The current one is v2.2.1, and the options on this page are part of it. They are not on the standard CDN tag yet.

Self-hosting needs a site where you can add files, such as a Next.js or custom app, or WordPress with file access. On hosted builders (Shopify, Framer, Webflow, Squarespace, Wix) and in Google Tag Manager, use the standard tag.

1. Download and verify

Download the helper script and run it with the version you want and the folder to install into:

curl -fsSLO https://cdn.trylapis.com/pixel/self-host.sh
bash self-host.sh 2.2.1 ./public/lapis

The script downloads lapis-pixel.js and lapis-pixel-gate.js from the pinned folder https://cdn.trylapis.com/pixel/v2.2.1/ and checks them against the published SHA256SUMS. Files in a pinned folder never change. If a download fails or a checksum does not match, it installs nothing, so it is safe to run on every build.

It is a short shell script and the link opens as plain text in a browser, so read it before you run it.

If you prefer not to run a script, these commands do the same thing:

base=https://cdn.trylapis.com/pixel/v2.2.1
curl -fsSL -O $base/lapis-pixel.js -O $base/lapis-pixel-gate.js -O $base/SHA256SUMS
shasum -a 256 -c SHA256SUMS   # on Linux: sha256sum -c SHA256SUMS

2. Serve both files from one folder

Publish lapis-pixel.js and lapis-pixel-gate.js side by side, for example at /lapis/lapis-pixel.js and /lapis/lapis-pixel-gate.js. The pixel loads the gate file from next to itself whenever it has to wait for consent, so the two must share a folder.

3. Add the script tag

Point the tag at your own copy:

<script async src="/lapis/lapis-pixel.js" data-key="YOUR_API_KEY"></script>

In Next.js, with the files in public/lapis/:

// app/layout.tsx
import Script from "next/script";

<Script
  src="/lapis/lapis-pixel.js"
  data-key="pk_YOUR_PIXEL_KEY"
  strategy="afterInteractive"
/>

Everything on the Lapis Pixel page still applies: the same ad URL parameters, the same lapis() calls, and the same lapis_sid cookie.

With the standard tag, the Lapis CDN decides from the visitor’s location who must give consent first, and serves a consent gate in place of the pixel to visitors in the EU, EEA, UK and Switzerland. A file served from your own site does not pass through that check.

A self-hosted pixel falls back to the browser’s time zone, which misses a European visitor whose device is set to another zone. Lapis still drops that visitor’s events on its servers, but the cookies would already be set. So choose one of these:

  • Load the pixel only after consent for those visitors, the way you gate your other marketing tags, and add data-consent="granted" to the tag when you do.
  • Add data-consent="required" if you show a consent banner to every visitor. The pixel then waits for your banner’s marketing consent everywhere. Without a banner signal it never starts.

The consent tools the pixel detects are listed under Privacy and consent.

Options in v2.2.1

All optional. Add them as attributes on the script tag.

Attribute Effect
data-identity="off" The pixel never hashes an email. By default it hashes one only when a visitor submits a form that contains an email field.
data-url="strip" Every URL the pixel sends (page, referrer, link targets, form actions) keeps only the attribution parameters: utm_*, lapis_* and ad click IDs. All other query parameters and the fragment are dropped in the browser. Use it if your app puts tokens or account data in URLs.
data-landing-url, data-landing-ts, data-landing-referrer The landing URL, arrival time and referrer you saved when the visitor arrived. Use these if you load the pixel late. See Loading the pixel late.
data-consent="required" Wait for marketing consent for every visitor. See step 4.
data-debug Log every event to the browser console while you test.

Loading the pixel late

If you start your marketing tags after the first interaction or after a delay, a visitor may have moved to another page by the time the pixel loads, and the ad parameters are gone from the URL. Save the landing as early as possible on every page:

<script>try{var s=sessionStorage,l=location;if(!s.lapisLanding||l.search&&document.referrer.indexOf(l.origin)!==0)s.lapisLanding=JSON.stringify({url:l.href,referrer:document.referrer,ts:Date.now()});window.lapisLanding=JSON.parse(s.lapisLanding)}catch(e){}</script>

The pixel reads window.lapisLanding when it loads. You can pass the same values as data-landing-url, data-landing-ts and data-landing-referrer instead. Always include the arrival time: the pixel uses it to tell a new ad click from an older one, and it ignores a saved landing that is older than the current visit or older than 30 days.

Linking visitors to your users

Call this when a visitor signs up or logs in, with your own database user ID (never an email):

lapis("identify", { user_id: "48213" });

Lapis stores a hash of the ID. Send the same ID as external_user_id in your Conversion API events, alongside the click ID as usual. A later event for that user, such as a first payment weeks after signup, then still matches the visit they signed up in, even if the click ID is no longer at hand.

On logout, lapis("reset") forgets the visitor, which matters on shared devices.

Content Security Policy

The script now comes from your own site, so script-src needs nothing new. In connect-src, allow https://api.trylapis.com. From v2.2.1 the pixel sends events to that one host only.

Updating

A pinned version never changes, so nothing reaches your site until you fetch it:

  1. Run the script again with the new version number, or change the number in your build.
  2. Deploy.

Lapis announces new versions, and every event carries the pixel version, so we can tell you when your copy has fallen behind.

Versions

v2.2.1  (2026-11-13)
98c5afb2942c6bf4a92b5dafd834c46a427be3a938e73832e059b5758aaa8f93  lapis-pixel.js
b4d82e92bf7de6be4faa6dca792d45505ea7358f08e454c57789a8ffb60d5e68  lapis-pixel-gate.js

FAQ

Can I load the pinned CDN URL directly instead of hosting the files?

Not yet. The pinned folder is there to download from. A site that loads it directly does not get the location-based consent gate, so use the standard tag or host the files yourself.

Does the self-hosted pixel run on localhost?

No. The pixel stays off on localhost and file: pages, so local development does not send events.

Do I still need the Conversion API?

Yes. Self-hosting changes where the script comes from, not what it can see. Send your verified conversions from your backend through the Conversion API as before.

Was this page helpful?