Set up PingAura Telemetry (first-party collector)

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 connectors, this is data you own end to end: there is no third-party platform in the path.

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, or a Cloudflare Worker, any other framework, etc).

Step 1 — Create an ingest key

1. Go to Settings → API Keys.
2. Create a new key with the write scope.
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 is a write-scoped API key. Keep it on your server — it is not a public browser key.

Step 2 — Confirm your domain

Events carry the domain they belong to. It must match a domain registered on your PingAura account exactly (for example example.com). If the domain isn't registered, the events are rejected.

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

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 (it's capped by the SDK's request timeout). 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.

Troubleshooting

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

• Ingest key — make sure it's valid, not revoked, and has the write 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 match a domain registered on your account exactly. Watch for typos and www/subdomain differences.
• Send rate — sending a very high volume from one source can be throttled. Back off and retry.

The dashboard counts unique events, so safe retries won't double-count.