Kismet Telemetry

Kismet Telemetry records page and crawler requests that reach your application runtime, gives consenting visitors a first-party session on your domain, and joins a later booking to that session. Your page never waits on Kismet: a first-time visitor gets a locally minted session and the reconciliation runs after the response. Server-side collection also records crawler requests that reach the adapter without executing browser JavaScript.

Review before installing

Read what is installed and sent, including the browser tracker and source-access boundaries. Retrieve your collection tracking key from the collection’s Keys page after onboarding. The dedicated install report is separate work; the table below describes available evidence, not automatic provisioning of a reporting account.

Pick your framework

The core, Next.js and Node adapters have passed conformance. Core and Next.js 1.1.1 and Node 1.0.2 are published on npm. The standalone WordPress 1.1.1 ZIP has passed local WordPress and mixed-site browser validation; your site still needs consent and cache acceptance. Django is planned. Install on Next.js, on Node, on WordPress, or on Django. Anything else wires from the contract and the core’s reference adapter.

Next.js1.1.0 on npm@kismet-tech/telemetry-nextMiddleware plus a root-layout seed component. App Router, Edge or Node runtime.Install on Next.js →Node1.0.1 on npm@kismet-tech/telemetry-nodeExpress and Connect middleware on the raw request and response; Fastify, Koa and plain node:http too.Install on Node →WordPress1.1.0 ZIPkismet-telemetry pluginA standalone, cache-safe plugin with a settings screen. Coexists with Kismet Elements.Install on WordPress →Djangonextkismet-telemetry on PyPIMiddleware, a consent callable and a template tag on the same contract. Wire it yourself today from the contract page.Install on Django →

Request two values from Kismet during onboarding: the collection slug and the collection’s tracking key (ctk_…), which stays server-side and never reaches a page. Confirm your production and staging hostnames are on the collection’s authorized domains.

How it works

The adapter records requests that reach its runtime. WordPress full-page cache hits bypass the PHP beacon. Identity reconciliation and event delivery do not block page delivery; local middleware overhead should still be measured.

1. Classify the URL. A route profile you fill in once says which URLs are property pages, results pages, the checkout path and agent surfaces such as llms.txt. Assets and your own API routes are skipped before anything else runs.
2. Resolve the visitor. A threaded ?kid_sid= on the URL wins, then the _kid_sid cookie. Bots and visitors in a consent jurisdiction without consent get nothing: no new session id, no session cookie and no identity reconciliation. Server-plane events still run. Everyone else on a cold visit gets an id minted locally, and Kismet is told about it after the response is sent.
3. Record the server-plane event. One event per page and per agent surface, sent in the background with a two-second bound and failures swallowed. Bots are classified at ingest and never carry a session, even when they echo a shared link.
4. Hand the decision to the page. In Next.js through request headers the root layout reads; in Node on req.kismet and res.locals.kismet; in WordPress through a never-cached endpoint the head bootstrap calls; a custom adapter must follow the same contract.
5. Set the cookies and seed the page. _kid_sid for 90 days. Optional returning-visitor recognition in Next.js and WordPress 1.1.0 adds an authority-issued _kid_vid for up to 400 days after explicit consent and collection enablement. Browser policies and cookie deletion can shorten either lifetime. Cookies are set on the dotted serving domain so one session survives www to apex and a WordPress root to a Next.js app. The page carries one inline script that seeds the id and then loads the browser tracker, so the tracker adopts the server’s session instead of minting its own. Next.js seeded responses and per-visitor anchor responses are private, no-store; the WordPress head bootstrap remains safe to cache.
6. Join the conversion. One server-side booking-bridge call from the code that knows the reservation succeeded, keyed on the same _kid_sid. Saves, date picks and the book button reach Kismet through the browser helpers.

The contract specifies each step exactly: grammars, cookie attributes, request bodies, timeouts, and what an adapter may never do.

Returning visitors

Enable optional _kid_vid recovery using the returning-visitor guide. This links a later session to the same collection-scoped visitor. It requires the 1.1.0 core/Next.js or WordPress release, explicit consent and Kismet enabling your collection. It does not identify a guest across devices or sign them in. Package version 1.1.0 is not the separate HTTP Contract 1.1 roadmap.

Consent

Consent gates the session only: the cookies, the mint, the reconcile, the seed id. It does not gate the server-plane event, which is recorded for every request with a null session when no session was allowed. The default gate is a country list read from a Cloudflare or Vercel country header. Core 1.1.1, Next.js 1.1.1, Node 1.0.2 and WordPress 1.1.1 deny cookies when that header is missing or unknown. Every adapter takes a consent hook that reads your consent manager’s saved choice; consentFromCookie(name, pattern) covers the common case, and the WordPress plugin reads the cookie from its settings.

What you get with and without a Kismet catalog

	Install alone	Paired with a Kismet catalog
Crawler and AI agent visits, by agent and page	yes	yes
Verified AI referrals (a literal AI referrer or tagged link)	yes	yes
Per-property funnel stages	requires property mapping	requires a registered serving URL or a known Kismet slug in contract 1.0

Contract 1.0 limit: externalListingId can be emitted, but ingest-side resolution and generic conversions are Contract 1.1 additions. For property-level attribution today, arrange a registered serving-URL mapping or use a known Kismet property slug. Confirm backend support before relying on the 1.1 fields.

Conformance

Every adapter, ours or yours, ships the same suite: @kismet-tech/telemetry/conformance starts a stub authority and a stub relay and drives an adapter through the eight requirement groups of the contract. An adapter that does not pass does not ship. The core’s reference adapter passes it and is the worked example for wiring a framework we do not ship.

Packages

Package	What it is
@kismet-tech/telemetry	The core: contract 1.0 as code, browser helpers, the conformance harness. Node 20+, Cloudflare Workers, or any runtime with fetch.
@kismet-tech/telemetry-next	Next.js middleware and the root-layout seed component.
@kismet-tech/telemetry-node	Express and Connect middleware on the raw request and response.
kismet-telemetry (WordPress)	A standalone plugin, cache-safe, with a settings screen.
kismet-telemetry (Django)	Next on the same contract.