35. Reach Beacon SDK (npm)

Your Klariton touchpoints already measure which AI agents read Klariton-served pages. The Reach Beacon extends that measurement to your main domain: a tiny server-side hook reports page views to Klariton, and two things show up in your Studio.

• Agentic Reach for your own pages. Which AI and search bots (GPTBot, ClaudeBot, PerplexityBot and friends) read which pages of your website.
• Company visits. Which companies visit your site, resolved server-side from the visitor IP. Anonymous visitors create no event at all.

No client-side script, no cookies, no consent banner impact, no effect on page speed: the beacon fires fire-and-forget from your server middleware and never delays a response.

Install

npm install @klariton/beacon

The package is dependency-free, runs on the Edge runtime and on Node 18+, and ships TypeScript types.

Next.js quickstart

If your project has no middleware.ts yet, this is the whole integration:

middleware.ts

import { createKlaritonMiddleware } from '@klariton/beacon/next';

export default createKlaritonMiddleware({
  tenant: 'your-org-slug',
  key: process.env.KLARITON_BEACON_KEY ?? '',
});

export const config = {
  matcher: ['/((?!_next/|api/|.*\\..*).*)'],
};

If you already have a middleware, add a single call inside it:

middleware.ts

import type { NextFetchEvent, NextRequest } from 'next/server';
import { reportToKlariton } from '@klariton/beacon/next';

export function middleware(req: NextRequest, event: NextFetchEvent) {
  reportToKlariton(
    { tenant: 'your-org-slug', key: process.env.KLARITON_BEACON_KEY ?? '' },
    req,
    event,
  );
  // ... your existing logic
}

Configuration

Option	Meaning
tenant	Your org slug from Klariton Studio
key	Your beacon key. A server-side secret: set it as an environment variable, never expose it to the browser, never commit it

Set KLARITON_BEACON_KEY in your production environment only. Without a key the SDK is a silent no-op, so local development and preview deployments send nothing.

What gets reported

Per page view the middleware sends: host, path, the User-Agent header, the visitor IP (optional), the referrer domain and the raw query string.

• Bots: Klariton matches the User-Agent against known AI and search crawlers and records a page read for your domain.
• Companies: the visitor IP is used for one transient company lookup and is never stored or logged. Only identified companies create a visit event; anonymous traffic is discarded.
• Attribution: utm_* parameters from the query string are attached to company visits, so a visit from an AI answer or a campaign is attributed correctly.

Static assets, /_next/ internals and /api/ routes are filtered out both by the recommended matcher and by the SDK itself.

Other environments

The core is framework-agnostic. Anything that can run fetch can report a page view, which is how adapters for other stacks (SvelteKit, Nuxt, Express, …) work:

import { sendReachBeacon } from '@klariton/beacon';

await sendReachBeacon(
  { tenant: 'your-org-slug', key: process.env.KLARITON_BEACON_KEY ?? '' },
  {
    host: 'www.example.com',
    path: '/services',
    userAgent: requestUserAgent,
    clientIp: visitorIp, // optional, enables company resolution
    query: rawQueryString, // optional, enables utm attribution
  },
);

sendReachBeacon never throws and times out after three seconds, so it is safe to call from any request path.

Schema.org JSON-LD (@klariton/beacon/schema)

Since 0.3.0 the SDK also helps you embed AI-visible structured data. @klariton/beacon/schema fetches the Schema Export API and returns the schema.org @graph string for server-side rendering — so AI crawlers (GPTBot, ChatGPT-User, PerplexityBot, ClaudeBot) can read it. They do not run JavaScript, so client-injected JSON-LD is invisible to exactly the crawlers you want to reach. Render it in a Server Component:

// Next.js server component, e.g. app/services/[slug]/page.tsx
import { fetchKlaritonSchema } from '@klariton/beacon/schema';

export default async function ServicePage({ params }: { params: { slug: string } }) {
  const jsonLd = await fetchKlaritonSchema('your-org-slug', `${params.slug}-leistungen`);
  return (
    <>
      {jsonLd && (
        <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: jsonLd }} />
      )}
      {/* ...page content... */}
    </>
  );
}

fetchKlaritonSchema(org, product, options?) is framework-agnostic and fail-open (any error resolves to null, never throws). listKlaritonSchemaSlugs(org) returns the available product slugs so you can map your own routes. The structured data itself is authored in Studio; the SDK only fetches it and you render it server-side.

Beacon or tracking webhook?

If your domain already feeds company visits into Klariton through a visitor identification webhook (for example Snitcher), pick one source per domain for company visits, otherwise the same company can appear twice. The bot measurement is unaffected: it only comes from the beacon.

Getting your key

Beacon keys are currently issued by Klariton during onboarding. Self-service key management in Studio (create, rotate, revoke under Settings) is on the roadmap.