Set up PingAura Telemetry

PingAura Telemetry is PingAura's first-party analytics collector. You send pageview events from your own server, and PingAura classifies them into human pageviews, AI-assistant referrals (ChatGPT, Perplexity, Gemini, and more), and AI bot crawls, then attributes them to your content. Unlike the GA4, Search Console and Cloudflare tabs, it is measured on your own server, not through Google or Cloudflare.

Before you begin

• Your domain is added to PingAura (the same domain you will send events for).
• PingAura Telemetry is available on the Enterprise plan. If you don't see the tab, contact your account team.
• You can add a few lines to your site's server (Next.js, Node.js, a Cloudflare Worker, or another JavaScript server). On WordPress, use the WordPress plugin instead.

Step 1: Create an ingest key

1. Go to Workspace settings → API & MCP.
2. Create a new key with the ingest scope only.
3. Copy the key immediately. It is shown only once. Store it as an environment variable (for example PINGAURA_INGEST_KEY); never commit it.

An ingest key can only send telemetry events; it can't read or change account data. Keep it on your server. It is not a public browser key. To count clicks from a public page, use a browser key instead.

Step 2: Confirm your domain

Events carry the domain they belong to. Set domain to the bare host registered on your PingAura account (for example example.com, without https://, www. or a path). If the domain isn't registered, the events are rejected.

If the domain is registered with a path (for example example.com/business), still set domain: 'example.com', and send only the pages under that path plus your crawler files. Pages outside the path are ignored, so there is no need to send them. On Node or Cloudflare, use shouldTrack:

const CRAWLER_FILES = ['/robots.txt', '/llms.txt', '/llms-full.txt', '/sitemap.xml'];
const PREFIX = '/business';

// pass alongside writeKey and domain
shouldTrack: (path, { method }) =>
  (method === 'GET' || method === 'HEAD') &&
  (CRAWLER_FILES.includes(path) ||
    ((path === PREFIX || path.startsWith(`${PREFIX}/`)) && !/\.\w+$/.test(path))),

On Next.js, add <TrackPageView/> only to pages under the path.

Step 3: Install the SDK

Install the collector package:

npm install @pingaura/telemetry

Pick the entry point for your stack. Each needs your ingest key and your registered domain.

Next.js (App Router)

Two files: a proxy that records the request path, and a <TrackPageView/> component in the pages you track. A pageview fires only when a real page renders, so 404s and bot probes aren't counted. The ingest key is read from PINGAURA_INGEST_KEY.

// proxy.ts  (on Next 15, name it middleware.ts and export `middleware`)
import { pingauraMiddleware } from '@pingaura/telemetry/next';

export const proxy = pingauraMiddleware();

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

// add to each page you track, not the root layout (that would count 404s)
import { TrackPageView } from '@pingaura/telemetry/next';

export default function Page() {
  return (
    <>
      <TrackPageView domain="example.com" />
      {/* ...page content... */}
    </>
  );
}

Already have a proxy or middleware? Skip pingauraMiddleware and set the path header inside your existing one:

import { pingauraRequestHeaders } from '@pingaura/telemetry/next';

// in your existing proxy.ts / middleware.ts, when you return next()
return NextResponse.next({
  request: { headers: pingauraRequestHeaders(request) },
});

Node / Express

import { analyticsMiddleware } from '@pingaura/telemetry/node';

app.use(
  analyticsMiddleware({
    writeKey: process.env.PINGAURA_INGEST_KEY,
    domain: 'example.com',
  }),
);

Cloudflare Worker

Use the edge or your server, not both. If you run the Cloudflare Worker and also the Node or Next.js SDK on your server, pages that miss the Cloudflare cache are counted twice. If your site is behind Cloudflare, the Worker is usually the better choice: it also sees cached pages and AI crawlers that never reach your server.

trackEdge is fire-and-forget: it reads only headers, never consumes the body, and never throws.

import { trackEdge } from '@pingaura/telemetry/cloudflare';

export default {
  async fetch(request, env, ctx) {
    const response = await fetch(request);
    trackEdge(request, response, ctx, {
      writeKey: env.PINGAURA_INGEST_KEY,
      domain: 'example.com',
    });
    return response;
  },
};

Any other server

import { createClient } from '@pingaura/telemetry';

const analytics = createClient({
  writeKey: process.env.PINGAURA_INGEST_KEY,
  domain: 'example.com',
});

await analytics.pageView({ url: request.url });

On a serverless runtime, keep the await so the event is sent before the function freezes. On a long-running server (e.g. Express), you can drop the await to keep it fully fire-and-forget. pageView() never throws.

Don't see your framework or language?

The SDK covers Node, Next.js, and Cloudflare Workers, plus a generic client for any other JavaScript or TypeScript server.

Want a first-class SDK for your stack? Tell us which framework or language you'd like us to support and we'll prioritise it. Request framework support →

Step 4: Deploy and verify

1. Deploy your server with the ingest key set.
2. Visit a few pages on your site.
3. Open the PingAura Telemetry tab in PingAura. Once the first events land, the setup panel is replaced by your dashboard. First data usually appears within a minute.

The tab then shows AI Source Breakdown, AI Bot Crawls, Human vs Bot Traffic, Traffic by Country, Top Pages, AI bot access, Crawler files and PingAura Content Attribution.

Troubleshooting

If events aren't arriving, check these in order:

• Ingest key: make sure it's valid, not revoked, and has the Ingest scope. If in doubt, create a new one.
• Plan: PingAura Telemetry must be enabled on your plan. If it isn't, contact your account team.
• Domain: the domain you send must be a host registered on your account. Watch for typos and subdomain differences. If the domain is registered with a path, events for pages outside it are skipped, not rejected.