Install & Configure

You're about to unlock powerful web and marketing data. Let's get you set up!

Need your Account ID? Find it in the URL when viewing your account: app.listenlayer.com/account/abc123 → your ID is abc123

Choose Your Method

Install with GTM

The simplest way to get started. No code changes to your website!

Option A: Use Our Wizard

Let us do the work for you:

Log in to ListenLayer
Go to Settings → Installation
Click Install with GTM

Done! We'll add the tag to your GTM container automatically.

Option B: Add It Yourself

Open Google Tag Manager
Tags → New → name it ListenLayer
Tag Configuration → Custom HTML
Paste this:

<script src="https://sdk.listenlayer.com/ll.js?id=YOUR_ACCOUNT_ID" async></script>

Triggering → All Pages
Save and Publish

You're live! ListenLayer is now running on your site.

Install Directly

Add this to your website's <head> tag:

<script src="https://sdk.listenlayer.com/ll.js?id=YOUR_ACCOUNT_ID" async></script>

Where's the <head> tag?

Platform

Location

WordPress

Appearance → Theme Editor → header.php

Shopify

Online Store → Themes → Edit Code → theme.liquid

Squarespace

Settings → Advanced → Code Injection

Webflow

Project Settings → Custom Code

Custom

Your HTML file, between <head> and </head>

Once added, you're tracking! Check your dashboard to see data flowing in.

Verify It's Working

Quick check to make sure everything's connected:

Visit your website
Press F12 to open Developer Tools
Go to the Network tab and refresh the page
Filter for ll.js — you should see it load with status 200

See ll.js loading? You're all set! Data should appear in your dashboard within a few minutes.

Troubleshooting

ll.js not loading?

Double-check your Account ID in the script tag
Clear your browser cache and refresh
Check if an ad blocker is blocking the script
Verify GTM is published (if using GTM)

Script loads but no data in dashboard?

Type _ll in the Console tab — you should see an object
Check Console for JavaScript errors
Verify your domain is added in Settings → Domains

Enable Preview Mode

For deeper testing, use Preview & Debug mode to watch events fire in real-time as you browse you website. This requires enabling your website to display in an iframe.

One-time setup REQUIRED: Add this header to your server to allow your wesbite to load in our previewer.

Enable Preview for Your Website

Content-Security-Policy: frame-ancestors 'self' *.listenlayer.com;

See Preview & Debug for platform-specific instructions.

Custom Events Stub

If you're sending Custom Events, add this stub script above Google Tag Manager to prevent race conditions.

Add the Stub for Custom Events

If you're calling SDK methods like _ll.track(), _ll.ecommerce.viewItem(), or _ll.identifyPerson(), you need the stub.

Why? Your code might run before ListenLayer finishes loading. The stub catches those early calls so nothing gets lost.

Add the Stub

Paste this above GTM (or above the ListenLayer script):

<script>"use strict";(()=>{(function(){var r,i;let n=window;if((r=n._ll)!=null&&r._stub)return;let l=((i=n._ll)==null?void 0:i.q)||[];n._ll={q:l,_stub:1};function u(e){return new Proxy({},{get:(t,o)=>{if(typeof o=="string")return(...s)=>{n._ll.q.push([`${e}.${o}`,...s])}}})}let c=["ecommerce","video","chat","scheduling","form"];for(let e of c)n._ll[e]=u(e);let a=["track","identifyPerson","pageview","debug"];for(let e of a)n._ll[e]=(...t)=>{n._ll.q.push([e,...t])};n._ll.waitFor=e=>{let t=()=>{var o,s;(s=(o=n._ll)==null?void 0:o.isReady)!=null&&s.call(o)?e():setTimeout(t,50)};t()},n._ll.ready=()=>new Promise(e=>{n._ll.waitFor(e)}),n._ll.isReady=()=>!1})();})();</script>

Use waitFor()

Wrap your custom event calls to ensure they do not run too early:

_ll.waitFor(function() {
  _ll.track('button_clicked', { button: 'signup' });
});

Never put the stub inside GTM! GTM loads asynchronously, so the stub won't be ready in time. It must be directly in your HTML.

Full Setup Example (Stub + GTM)

Here's what your <head> should look like:

<head>
  <!-- 1. ListenLayer Stub (must be first!) -->
  <script>"use strict";(()=>{(function(){var r,i;let n=window;if((r=n._ll)!=null&&r._stub)return;let l=((i=n._ll)==null?void 0:i.q)||[];n._ll={q:l,_stub:1};function u(e){return new Proxy({},{get:(t,o)=>{if(typeof o=="string")return(...s)=>{n._ll.q.push([`${e}.${o}`,...s])}}})}let c=["ecommerce","video","chat","scheduling","form"];for(let e of c)n._ll[e]=u(e);let a=["track","identifyPerson","pageview","debug"];for(let e of a)n._ll[e]=(...t)=>{n._ll.q.push([e,...t])};n._ll.waitFor=e=>{let t=()=>{var o,s;(s=(o=n._ll)==null?void 0:o.isReady)!=null&&s.call(o)?e():setTimeout(t,50)};t()},n._ll.ready=()=>new Promise(e=>{n._ll.waitFor(e)}),n._ll.isReady=()=>!1})();})();</script>

  <!-- 2. Google Tag Manager (or directly place ListenLayer main script -->
  <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
  new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
  j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
  'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
  })(window,document,'script','dataLayer','GTM-XXXXXX');</script>
</head>

Custom Tracking Domain

Run ListenLayer's client-side activity over your own sub-domain, increasing data reliability. We recommend that the hostname (top domain) matches your primary website domain where ListenLayer is running.

<script src="https://intl.yourdomain.com/ll.js?id=YOUR_ACCOUNT_ID" async></script>

Why bother?

Bypass ad blockers that target third-party scripts
More reliable, long-term user identification
Keep everything on-brand and maintain user confidence

Coming soon - want early access? Contact us!

Cross-Domain Tracking

Track visitors seamlessly as they move between your related domains—like your main website, shop, blog, or app subdomains.

When do you need this? If your business operates across multiple domains (e.g., example.com , shop.example.com, and www.example2.com) then visitors moving across these domains are treated as separate users by default. Cross-domain tracking allows us to unifiy their activity and reduce self-referral, direct traffic.

How to Enable

Log in to ListenLayer
Go to Settings → Domains
Add all domains where ListenLayer is installed
Cross-Domain Tracking is autoamtically enabled for your domains, but can be disabled.

ListenLayer's AI automatically detects your website structure and adds domains that you commonly link to an run our script on. You can lock your domains on the settings page, to avoid new domains being added automatically.

Once configured, ListenLayer automatically decorates links between your domains.

How It Works

When a visitor clicks a link from one of your domains to another, ListenLayer adds a _ll_xd parameter to the URL:

https://shop.example.com/products?_ll_xd=eyJkIjoiZXhhbXBsZS5jb20iLCJ0cyI6MTc0MDQxMjgwMDAwMH0

This parameter contains encoded information about the user and their device:

Field

Purpose

Source domain

Where the click originated

Timestamp

When the link was clicked (for security)

Device ID

Links the visitor across domains (for identified users)

Tracking mode

Preserves consent and tracking preferences

The target domain reads this parameter, links the device to its existing profile, and removes the parameter from the URL (keeping your URLs clean) while retaining any of your other parameters.

Security & Privacy

Time-limited validity

The _ll_xd parameter expires after 60 seconds. This prevents:

Bookmarked links from incorrectly linking visitors
Shared links from merging different visitors
Replay attacks

Consent-aware

If a visitor is in Do Not Track mode, links are not decorated
Consent preferences are preserved across domains
Anonymous visitors are linked via browser fingerprint (no PII in URL). The ll_xd is NOT an identifier for the user. For anonymous users, it simply passes their consent state across domains to ensure accurate compliance.

Automatic cleanup

The parameter is removed from the URL immediately after processing using history.replaceState, so visitors never see cluttered URLs.

Which links are decorated?

ListenLayer decorates links that:

Point to a domain in your cross-domain group
Use http:// or https:// protocol
Don't already have the _ll_xd parameter

Links that are not decorated:

Same-domain links (no decoration needed)
Links to domains not in your cross-domain group
mailto:, tel:, or javascript: links
Links when the visitor is in Do Not Track mode

Preview Mode Across Domains

When using Preview & Debug mode, additional parameters maintain your preview session across domains. You will only see these when in preview mode.

Parameter

Purpose

_ll_preview

Preview session ID

_ll_preview_salt

Ensures consistent anonymous IDs during testing

_ll_mock_geo

Preserves mock geo location for testing

This allows you to test your cross-domain setup in preview mode and see the complete visitor journey in real-time.

Testing tip: Use Preview Mode to click through your domains and verify visitors are being linked correctly. You'll see the same Device ID appear on each domain. When it's time to reset your Preview Session, ListenLayer automatically attempts to clean-up preview cookies on all of the domains you've visited, but it's not always possibley so you might need click "Reset Session" once while on each domain.

PreviousIntroduction NextConsent Management

Last updated 2 hours ago

Was this helpful?

Good night

hashtagChoose Your Method

hashtagVerify It's Working

hashtagEnable Preview Mode

hashtagCustom Events Stub

hashtagCustom Tracking Domain

hashtagCross-Domain Tracking

hashtagHow to Enable

hashtagHow It Works

hashtagPreview Mode Across Domains

Choose Your Method

Verify It's Working

Enable Preview Mode

Custom Events Stub

Custom Tracking Domain

Cross-Domain Tracking

How to Enable

How It Works

Preview Mode Across Domains