Loamly works with both client-side and server-side GTM. Client-side GTM tracks browser page views and detects AI visitors through referrers and Loamly's classifier. Server-side GTM (sGTM) goes further — it detects raw AI bot crawlers (ChatGPT-User, GPTBot, ClaudeBot, PerplexityBot) at the HTTP level, the same way our DNS proxy does, without any DNS changes.

Client-side GTM

The client-side tag loads the Loamly tracker script on every page. It tracks page views, detects AI traffic via referrer signals, and supports SPA route changes automatically.

Import template

Download template.tpl from the loamly/gtm-loamly-template GitHub repo (click the download/raw button)
Open tagmanager.google.com and select your Web container
Go to Templates → New
Click the three-dot menu (top right) → Import
Select the downloaded template.tpl file → Save
Go to Tags → New
Click Tag Configuration → select "Loamly Analytics"
Enter your domain (e.g. example.com) — no API key needed
Click Triggering → select All Pages
Save → Submit → Publish

Template options

The template supports two optional settings:

Enable Debug Mode: Logs tracking events to the browser console
Disable Automatic Pageview: For SPAs where you want manual control over page tracking

Alternative: Custom HTML tag

If you prefer not to import a template, you can use a custom HTML tag instead.

Open tagmanager.google.com and select your Web container
Go to Tags → New
Click Tag Configuration → select Custom HTML
Paste this code:

<script>
(function() {
  var s = document.createElement('script');
  s.src = 'https://app.loamly.ai/t.js?d=yourdomain.com';
  s.defer = true;
  document.head.appendChild(s);
})();
</script>

Replace yourdomain.com with your actual domain
Click Triggering → select All Pages
Save → Submit → Publish

Important

Use the JavaScript snippet above, not a regular <script> tag. GTM requires dynamically creating the script element inside a Custom HTML tag.

Server-side GTM (sGTM)

If you run a GTM Server Container (Stape, Cloud Run, etc.), the Loamly sGTM template detects AI bot crawlers directly at the HTTP level — the same bots our DNS proxy detects — without any DNS changes.

It detects ChatGPT, Claude, Perplexity, Gemini, GPTBot and 10+ other AI crawlers by reading the raw HTTP request headers (User-Agent, RFC 9421 signatures) before any JavaScript runs. Most AI crawlers don't execute JavaScript, so this is the only way to catch them server-side.

What it detects

AI bot crawlers via User-Agent — ChatGPT-User, OAI-SearchBot, GPTBot, ClaudeBot, PerplexityBot, Google-Extended, Gemini-Deep-Research, Meta-ExternalAgent, Applebot-Extended, Cohere-AI, Copilot, YouBot
RFC 9421 HTTP Message Signatures — captures Signature, Signature-Input, and Signature-Agent headers from AI agents like ChatGPT and forwards them to Loamly for server-side verification
Bot-to-click matching — Loamly correlates bot crawl data with human visits from the same AI tool, showing which pages AI tools are recommending

This is functionally equivalent to the DNS proxy — same bots detected, same data pipeline, same dashboard. The only difference is that sGTM cannot do Ed25519 cryptographic verification of RFC 9421 signatures (sandbox limitation). Loamly verifies signatures server-side.

Prerequisites

A GTM Server Container running (Stape, Cloud Run, self-hosted, etc.)
Bot traffic must reach your sGTM endpoint. This works when your sGTM runs on a custom domain that receives site traffic (e.g. Stape custom domain, or sGTM behind a reverse proxy)
Your Loamly Workspace ID and API Key (from Loamly Settings)

Important: bot traffic must reach sGTM

If your sGTM only receives forwarded GA4 measurement events at a separate subdomain (e.g. metrics.example.com/g/collect), bot crawlers hitting your main domain won't reach it. For bot detection, your sGTM needs to be in the request path — either as the main domain endpoint or behind a reverse proxy that routes all traffic through it.

Install

Download template.tpl from GitHub
Open tagmanager.google.com → select your Server Container
Go to Templates → New
Click the three-dot menu (top right of the template editor) → Import → select the downloaded file → Save
Go to Clients → New
Select "Loamly AI Traffic Detection"
Enter your Workspace ID and API Key (from Loamly → Settings)
Save → Submit → Publish

Why Clients, not Tags?

Inside a Server Container, Google distinguishes between "Clients" and "Tags". A Client intercepts raw HTTP requests — that's what detects bots. A Tag only fires after GA4 events, which bots never trigger. That's why step 5 says Clients → New, not Tags → New. No trigger is needed — it automatically processes incoming requests and only intercepts AI bots. Your GA4 setup keeps working normally.

Configuration

Template settings

Workspace ID (required): Your Loamly workspace ID
API Key (required): Your Loamly workspace API key
Request Path Filter (default: /): Only process requests matching this path prefix. Use / for all pages, or /blog to detect bots only on your blog.
Only Claim AI Bot Requests (on by default): Only intercepts requests from known AI bots. Non-bot traffic passes through to your GA4 Client as normal. Keep this on.
Capture RFC 9421 Signatures (on by default): Reads Signature, Signature-Input, and Signature-Agent headers and forwards them to Loamly.
Enable Debug Logging (off by default): Logs to the sGTM server console. Turn on in Preview mode for testing.

How it works

AI bot crawls your site (GET /pricing)
        ↓
Your sGTM endpoint (ss.example.com)
        ↓
Loamly Client claims the request
(reads User-Agent + RFC 9421 headers)
        ↓
Returns 200 to bot immediately
        ↓
POST → app.loamly.ai/api/ingest/edge-visit (async)
        ↓
Same visits table as DNS proxy

Non-bot browser traffic is not claimed — your GA4 Client handles it normally. For browser pageview tracking in Loamly, use the client-side GTM template alongside this one.

Comparison table

Capability	Client-side GTM	sGTM Client	DNS proxy
Browser page views	Yes	Via client-side GTM	Yes
AI referrer detection (ChatGPT, Perplexity, etc.)	Yes	Via client-side GTM	Yes
Dark AI / Bing Copilot detection	Yes	Via client-side GTM	Yes
Raw bot crawl detection	No	Yes	Yes
RFC 9421 signature capture	No	Yes	Yes
Ed25519 crypto verification	No	No (server-side)	Yes (at edge)
Bot-to-click matching	No	Yes	Yes
Crawl analytics	No	Yes	Yes
Requires DNS changes	No	No	Yes
Requires sGTM server container	No	Yes	No

Recommended setup: Use client-side GTM for browser pageviews + AI referrer detection, and add the sGTM Client for raw bot crawl detection. This gives you the same coverage as the DNS proxy without any DNS changes.

Verify installation

Client-side tag:

In GTM, click Preview to enter debug mode
Visit your site in the preview tab
Check that the Loamly tag shows "Tag Fired"
Open app.loamly.ai → your workspace dashboard should show the visit within 1-2 minutes

sGTM Client template:

Open the sGTM Preview mode
Send a test request with an AI bot User-Agent:

curl -H "User-Agent: Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; ChatGPT-User/1.0; +https://openai.com/bot" \
  https://your-sgtm-domain.com/any-page

In the Preview panel, check that the Loamly Client claimed the request
If you enabled debug logging, check the sGTM console for [Loamly] Claimed request and [Loamly] edge-visit OK: 201
Open app.loamly.ai — the bot visit should appear in your dashboard

Single-page apps (SPAs)

Loamly auto-detects route changes in React, Vue, Angular, and other SPA frameworks. No extra configuration needed.

If you need manual control (e.g. custom transitions), enable "Disable Automatic Pageview" in the template settings and trigger pageviews manually:

// Trigger a pageview manually
if (window.Loamly) Loamly.pageview();

Troubleshooting

Tag not firing — check that the trigger is attached and the tag is not paused
No data in dashboard — wait 2 minutes, then verify your domain matches the workspace domain in Loamly settings
CSP errors — add app.loamly.ai to your Content Security Policy script-src directive
sGTM 401 errors — wrong API Key. Use the workspace API key from Loamly Settings → API Keys.
sGTM 403 errors — Workspace ID doesn't match the API key's workspace
sGTM Client not claiming — check that the bot request actually reaches your sGTM endpoint. Verify your sGTM domain setup. Enable Debug Logging and check the sGTM console.
GA4 events stopped working — make sure "Only Claim AI Bot Requests" is enabled. If disabled, the Client claims all requests and GA4 Client can't process them.
Debug mode (client-side) — open browser console and run Loamly.debug(true) to see tracking events
Debug mode (sGTM) — enable "Enable Debug Logging" in the template settings and check the sGTM server console for [Loamly] log entries

Need help? Email hello@loamly.ai