@nexoxa/analytics

Vercel-style web analytics — production OG flow: your app stores events on your server, Bridge reads over SSH.

Install

npm i @nexoxa/analytics

Next.js (or any framework on your server)

1. API route — persists to .nexoxa/analytics/ on the server:

// app/api/nexoxa-analytics/collect/route.ts

import { createAnalyticsCollectHandler, analyticsOptionsHandler } from "@nexoxa/analytics/node";



export const POST = createAnalyticsCollectHandler({

  // collectSecret: process.env.NEXOXA_COLLECT_SECRET, // optional

});

export const OPTIONS = analyticsOptionsHandler;

2. Client — same origin, no Bridge URL:

import { Analytics } from "@nexoxa/analytics/next";



<Analytics siteKey="nx_your_deployment_key" behavior />

3. Docker — mount data so Bridge SSH can read it:

environment:

  NEXOXA_DATA_DIR: /app/.nexoxa

  # NEXOXA_COLLECT_SECRET: ${NEXOXA_COLLECT_SECRET}

volumes:

  - ./nexoxa-data:/app/.nexoxa

Bridge

Connect SSH → Web Analytics reads .nexoxa/analytics/{siteKey}.jsonl from the server. Use the Engagement tab for scroll depth, top clicks, drop-off pages, and conversions. Bridge is a viewer only — it does not need to be running when visitors hit your site.

Production options

| Option | Purpose |

|--------|---------|

| NEXOXA_RETENTION_DAYS | Default 30 — drop older events |

| NEXOXA_MAX_MB | Default 8 per site — cap JSONL size |

| NEXOXA_COLLECT_SECRET | Reject POSTs without X-Nexoxa-Collect-Secret header |

| requireConsent + setAnalyticsConsent() | Gate tracking until cookie banner consent (EU) |

| behavior | Opt-in scroll depth, click, and rage-click tracking |

Paths are sanitized (query strings stripped) before storage.

Behavior analytics (opt-in)

Enable Clarity-style behavior signals on <Analytics />:

<Analytics siteKey="nx_your_key" behavior />

Or fine-grained:

<Analytics siteKey="nx_your_key" behavior={{ scroll: true, clicks: true, rageClicks: true }} />

• Scroll — milestones at 25%, 50%, 75%, 100% per page per session

• Clicks — buttons, links, [data-nx-track], submit inputs (password/email fields skipped)

• Rage clicks — 3+ rapid clicks on the same element

• Label CTAs with data-nx-track="cta-pricing" for readable element names in Bridge

Behavior events respect requireConsent the same as pageviews.

Heatmaps (Bridge)

Open Web Analytics → Heatmaps for click and scroll overlays on your live pages (when a preview URL is configured).

• Click heatmap — 24×24 grid from normalized click coordinates
• Scroll heatmap — attention bands at 25 / 50 / 75 / 100% depth
• Device filter — All, Desktop, Mobile, Tablet (viewport width or user-agent)

Requires behavior enabled on the SDK so click coordinates and scroll milestones are collected.

Custom events & conversions

import { track, flag, trackConversion } from "@nexoxa/analytics";



track("signup_completed", { plan: "pro" });

flag("new-checkout", true);

trackConversion("lead_submitted", { source: "contact_page" });

High-traffic sites with behavior enabled may need higher NEXOXA_MAX_MB or shorter NEXOXA_RETENTION_DAYS.

Privacy guidance for your site policy: asteron.nexoxa.com/privacy (section 8).

Product: asteron.nexoxa.com/integrations

MIT