# @nexoxa/analytics



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



## Install



```bash

npm i @nexoxa/analytics

```



## Next.js (or any framework on your server)



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



```ts

// 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:



```tsx

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



<Analytics siteKey="nx_your_deployment_key" behavior />

```



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



```yaml

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 />`:



```tsx

<Analytics siteKey="nx_your_key" behavior />

```



Or fine-grained:



```tsx

<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



```ts

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](https://asteron.nexoxa.com/privacy) (section 8).



Product: [asteron.nexoxa.com/integrations](https://asteron.nexoxa.com/integrations)



MIT