Quickstart

Adtivity turns your product, payment and on-chain data into a signal you can read, share and act on.

Connect Adtivity in 2 minutes4 steps · no config files

The shortest path from nothing to live data. Everything else in these docs is optional on top of this.

NEXT_PUBLIC_ADTIVITY_API_KEY=your_key_here

npm install @adtivity/adtivity-sdk

"use client"
import { useEffect } from "react"
import { init, initPageTracking, initClickTracking } from "@adtivity/adtivity-sdk"

export function Analytics() {
  useEffect(() => {
    init({ apiKey: process.env.NEXT_PUBLIC_ADTIVITY_API_KEY! })
    initPageTracking()
    initClickTracking({ trackAllButtons: true })
  }, [])
  return null
}

What to do next

Once data is flowing, the highest-value next step is identify(). Without it every error, recording and churn prediction shows a device ID instead of a person you can email. After that, pick whichever of session replay, error tracking or At-Risk Users you want first — they all run on the snippet you just added.

Two ways in

There are two routes into Adtivity — pick the one that matches how you build.

MCP Server Beta

adtivity-mcp is an AI-native setup assistant. Add it once to Claude Code or Cursor, tell your agent “Install Adtivity into this project”, and it detects your framework, installs the SDK, patches your entry file, and verifies the integration — no manual steps, no config wrestling.

Claude Code

Run once in your terminal. Claude Code picks it up on the next session.

claude mcp add adtivity -- npx adtivity-mcp

To use it across all your projects, add it globally:

claude mcp add --scope user adtivity -- npx adtivity-mcp

Cursor / Claude Desktop / Windsurf

Add to ~/.cursor/mcp.json (or the project-level .cursor/mcp.json):

{
  "mcpServers": {
    "adtivity": {
      "command": "npx",
      "args": ["adtivity-mcp"]
    }
  }
}

Five tools, one prompt

When you say “Install Adtivity”, the agent runs these tools in order:

Quick test

Confirm the server starts before adding it to your AI client:

npx adtivity-mcp

The process will hang — that means it's listening on stdio and is ready. Press Ctrl+C to exit.

Once connected to Claude Code or Cursor, open any project and try the prompt below. The demo shows you exactly what the agent will do:

Prompts that work well

After setup, you can also use the MCP tools individually:

Claude Prompt

No MCP server? No problem. Copy the prompt below and paste it directly into Claude (or any AI assistant). It contains everything the AI needs to install and wire up Adtivity in your project — SDK install, provider component, layout wiring, UTM & click tracking, and identity.

You are implementing Adtivity analytics into this project. Adtivity is a lightweight product analytics SDK for web apps. Follow these steps exactly:

## 1. Install the SDK
Run the appropriate command for this project's package manager:
  npm install @adtivity/adtivity-sdk
  # or: yarn add @adtivity/adtivity-sdk
  # or: pnpm add @adtivity/adtivity-sdk

## 2. Create the provider (Next.js App Router)
Create src/components/AdtivityProvider.tsx:

"use client"
import { useEffect } from "react"
import {
  init,
  initClickTracking,
  initPageTracking,
  initLocationTracking,
} from "@adtivity/adtivity-sdk"

export function AdtivityProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    init({
      apiKey: process.env.NEXT_PUBLIC_ADTIVITY_API_KEY ?? "",
      collectData: true,
    })
    initPageTracking()                          // auto-tracks page views + UTM source/medium/campaign
    initClickTracking({ trackAllButtons: true }) // auto-tracks ALL button/link clicks globally
    initLocationTracking()                      // enriches events with country/city from IP
  }, [])
  return <>{children}</>
}

For React (not Next.js), call the same functions inside a top-level useEffect in your App component instead.

## 3. Wrap the root layout (Next.js)
In src/app/layout.tsx, import AdtivityProvider and wrap children:

import { AdtivityProvider } from "@/components/AdtivityProvider"

// inside the JSX:
<AdtivityProvider>
  {children}
</AdtivityProvider>

## 4. Add the API key to .env.local
NEXT_PUBLIC_ADTIVITY_API_KEY=your_api_key_here

The user can get their API key at adtivity.xyz/dashboard → Settings → API Keys.

## 5. Identify users after sign-in
Wherever auth resolves (e.g. after login), add:

import { identify } from "@adtivity/adtivity-sdk"

identify(user.id, {
  email: user.email,
  plan: user.plan,          // optional
  createdAt: user.createdAt // optional
})

## 6. Track custom events (optional)
import { trackEvent } from "@adtivity/adtivity-sdk"

trackEvent("Checkout Completed", { amount: 99, plan: "pro" })
trackEvent("Feature Used", { feature: "export", format: "csv" })

## What you get automatically (no extra code)
- Page Viewed event on every route change with UTM params (utm_source, utm_medium, utm_campaign, utm_term, utm_content)
- UTM params persisted in sessionStorage — deep pages without UTMs still report the original source
- Every button/link click tracked with the element's text or aria-label as the event name
- Country, city, and region on every event via IP geolocation
- Anonymous ID (localStorage) and session ID (sessionStorage) stitched automatically

## Optional: suppress specific elements from click tracking
Add data-no-track to any element you don't want tracked:
<button data-no-track>Internal debug button</button>

## Optional: override the auto-derived click event name
<button data-adtivity-button-track="upgrade-plan-cta">Upgrade</button>
<a href="/pricing" data-adtivity-link-track="header-pricing-link">Pricing</a>

## Verify it works
Set debug: true in the init() call during development — you'll see every event logged to the console.
init({ apiKey: "...", debug: true })

Installation

Install the Adtivity SDK from npm. The package name is @adtivity/adtivity-sdk — note the double adtivity.

npm install @adtivity/adtivity-sdk

React Native — also install the async storage peer dependency:

npm install @react-native-async-storage/async-storage

The SDK ships as a single isomorphic package for both browser and React Native environments.

Authentication

The Adtivity SDK authenticates with a single API key. There's no separate sign-in step or token exchange — the key you pass to init() identifies your project for every event the SDK sends.

Find your key in Settings → API Keys in the Adtivity dashboard. Expose it to your client through a public env var, e.g. NEXT_PUBLIC_ADTIVITY_API_KEY.

Initialization

Initialise the SDK once at app startup. In Next.js this goes in your root layout or _app.tsx; in React, in your top-level component.

Basic setup

import {
  init,
  initClickTracking,
  initPageTracking,
  initLocationTracking,
} from "@adtivity/adtivity-sdk";

useEffect(() => {
  if (typeof window === "undefined") return;
  if (window.__ADTIVITY_BOOTSTRAPPED__) return;
  window.__ADTIVITY_BOOTSTRAPPED__ = true;

  const API_KEY = process.env.NEXT_PUBLIC_ADTIVITY_API_KEY;
  if (!API_KEY) {
    console.error("Adtivity SDK: API key is not configured");
    return;
  }

  init({
    apiKey: API_KEY,
    debug:  false,
    // Optional tuning:
    // batchSize: 10,
    // flushInterval: 5000,
  });

  initPageTracking();
  initClickTracking({ trackAllButtons: true });  // or omit options for data-attr opt-in mode
  initLocationTracking();
}, []);

Configuration options

Click Tracking

initClickTracking() attaches a single delegated listener to document.body — no onClick handlers, no manual track() calls needed. There are two modes:

Opt-in: data attribute tracking

Use data-adtivity-track on any clickable element.

<div data-adtivity-track="feature-card-click">
  Click me
</div>

Buttons

For <button> elements, use the more specific data-adtivity-button-track.

<Button data-adtivity-button-track="web3-simulate-token-transfer">
  <Rocket className="mr-2 h-5 w-5" />
  Simulate Token Transfer
</Button>

Links

For navigation, use data-adtivity-link-track.

<Link href="/cars" data-adtivity-link-track="header-nav-cars">
  <Car className="mr-2 h-4 w-4" />
  Cars
</Link>

Custom properties

Attach arbitrary JSON with data-adtivity-props.

<button
  data-adtivity-button-track="add-to-cart"
  data-adtivity-props='{"productId": "123", "price": 49.99}'>
  Add to Cart
</button>

Page Tracking

Once initPageTracking() is running, Adtivity fires a “Page Viewed” event automatically. Duplicate URLs are deduplicated — if the URL has not changed, no event fires. Not available in React Native.

Properties captured on every page view:

UTM Tracking

UTM parameters are captured automatically — no extra setup beyond calling initPageTracking(). When a visitor lands on any URL with UTM params, they are parsed, stored in sessionStorage, and merged into every “Page Viewed” event for the rest of that session.

Parameters captured

What a tagged Page Viewed event looks like

{
  "eventName": "Page Viewed",
  "properties": {
    "pageTitle":    "Adtivity — The metrics layer for founders",
    "path":         "/pricing",
    "fullUrl":      "https://adtivity.xyz/pricing?utm_source=google&utm_medium=cpc",
    "utm_source":   "google",
    "utm_medium":   "cpc",
    "utm_campaign": "summer_sale",
    "utm_term":     "product analytics",
    "utm_content":  "hero-cta"
  }
}

No extra code needed

UTM capturing is built into initPageTracking(). There is nothing else to call. If you need to read the current UTM values yourself (e.g. to pre-fill a form), the dashboard UTM Analytics report under KPIs shows breakdown by source, medium, and campaign.

Location Tracking

Calling initLocationTracking() enriches every event with geolocation derived from the visitor's IP address — country, region, city. No browser permission prompt; it's resolved server-side.

These fields are promoted to top-level in the API payload. Works in both browser and React Native.

Identity

The SDK gives you three layers of identity: anonymous ID (free), session ID (free), and user ID (one identify() call). Together they let Adtivity stitch a complete journey from first visit through sign-in and beyond.

Anonymous ID

An auto-generated UUID stored in localStorage, created the first time a visitor hits any page where the SDK is initialised. It persists across sessions, so a returning visitor on the same browser keeps the same anonymous ID.

// Automatically handled by the SDK.
// No code needed — created on first visit.

Session ID

A separate identifier scoped to a single browser tab. Open your site in a new tab and you get a new session ID; close the tab and that session ends.

// Automatically handled by the SDK.
// New session per tab/window.

User ID (custom)

When a user signs in, call identify(userId, properties?) with your own user ID. It is sent immediately — not batched. After this call, user_id is attached to all subsequent events for the session.

email and name are treated specially: they are stored against the person, not just recorded as event properties. Everything else you pass is kept as traits — plan, role, signup date, whatever you want to see next to a failing session.

import { identify } from "@adtivity/adtivity-sdk";

identify("user_12345", {
  email:      "user@example.com",
  plan:       "pro",
  signupDate: "2025-01-01",
});

Activity captured before sign-in

Identification almost always happens mid-session: someone browses anonymously, hits the error that made them give up, and only then signs in. Adtivity attributes that earlier activity retroactively by matching on the anonymous ID, so the error that actually mattered is still tied to a real person.

You do not have to do anything for this — call identify() whenever you learn who someone is, even late in the session.

Clearing identity on logout

Call resetIdentity() when a user signs out. Identity is persisted to localStorage so it survives a page refresh — which means without this, the next person to use a shared browser inherits the last one’s identity.

import { identify, resetIdentity } from "@adtivity/adtivity-sdk"

// on sign-in
identify("user_5150", { email: "dana@buyer.io", name: "Dana Okafor", plan: "pro" })

// on sign-out
resetIdentity()

Where the person shows up

Web3 / wallet identity

Use setWallet(address, chainId?) when a user connects a wallet. Both fields are automatically included on every subsequent event — trackEvent, identify, and trackTx alike. Pass null to clear on disconnect.

import { setWallet, identify } from "@adtivity/adtivity-sdk";

setWallet("0x742d35Cc...", "1");  // address, chainId
identify("0x742d35Cc...");        // use wallet as user ID

// On disconnect
setWallet(null);

Common chainId values: “1” Ethereum · “137” Polygon · “56” BNB Chain · “8453” Base · “42161” Arbitrum.

Tracking blockchain transactions

Use trackTx(name, properties?) for on-chain transactions.transaction_hash and contract_address are promoted to top-level fields in the API payload (not nested inside properties).

import { trackTx } from "@adtivity/adtivity-sdk";

trackTx("NFT Minted", {
  transaction_hash:  "0xdef...789",
  contract_address:  "0x123...456",
  token_id:          "42",
  price_eth:         "0.08",
});

Auto-Captured Data

Every event Adtivity sends — page view, click, identify — is automatically enriched with the following context. You don't need to attach any of it manually.

Session Replay

Session replay records the DOM and reconstructs what a user actually saw — mouse movement, clicks, scrolls, form input, navigation, and errors — so you can watch a session back instead of guessing from event names. It ships as a separate import, so you only pay for it if you use it.

npm install @adtivity/adtivity-sdk

import { SessionReplay } from "@adtivity/adtivity-sdk/session-replay"

const replay = new SessionReplay({
  apiKey: "YOUR_API_KEY",
})
replay.start()

Masking sensitive content

Password and credit-card inputs are masked automatically. Add your own selectors for anything else — masked elements keep their shape and position in the replay, but their text is replaced.

new SessionReplay({
  apiKey: "YOUR_API_KEY",
  maskSelectors: ["input[type=email]", "[data-sensitive]"],
  blockSelectors: [".customer-details"],  // replaced entirely with a placeholder
  sampleRate: 0.25,                    // record 25% of sessions
})

You can also mark elements in your markup without touching SDK config — data-adtv-mask masks the text, data-adtv-block replaces the element entirely.

Pausing and resuming

Stop recording around a screen you would rather not capture, then pick up again.

replay.pause()   // stop capturing, keep the session open
replay.resume()  // takes a fresh snapshot and continues
replay.stop()    // end the session and flush

Error Tracking

One call captures uncaught exceptions and unhandled promise rejections, batches them, and groups them into issues in your dashboard.

import { initErrorTracking } from "@adtivity/adtivity-sdk/errors"

initErrorTracking({ apiKey: "YOUR_API_KEY" })

How errors are grouped

Raw errors are a firehose — one broken component can throw thousands of times. Adtivity collapses them into issues using two rules:

• Variable data is stripped from the message. User 4821 not found and User 9134 not found are the same issue. IDs, UUIDs, URLs, emails and quoted strings are normalized before grouping.
• The stack’s first line of your own code wins. Cannot read properties of undefined gets thrown from dozens of unrelated places — those are different bugs, and are kept apart. Frames inside node_modules are skipped when deciding which code is yours.

Deploy-hashed bundle filenames (main.a1b2c3.js) group stably across releases, so a redeploy does not reset your issue history.

Reporting errors yourself

For errors you already catch, report them explicitly.

import { captureError } from "@adtivity/adtivity-sdk/errors"

try {
  await checkout()
} catch (err) {
  captureError(err, { step: "payment" })
}

Options

Filter out noise you cannot fix — a third-party script, a browser extension:

initErrorTracking({
  apiKey: "YOUR_API_KEY",
  release: "2.4.1",
  beforeSend: (error) => !error.message.includes("chrome-extension"),
})

Support Widget

When an error occurs, a small panel appears in the bottom-right corner offering the user a way to say what happened. Their report lands in your Support Inbox, linked to both the error and the session replay of what they were doing.

It is on by default with initErrorTracking(). Turn it off with widget: false if you only want silent error collection.

Everything visible is yours to rewrite:

initErrorTracking({
  apiKey: "YOUR_API_KEY",
  widgetTitle: "That didn't work",
  widgetMessage: "Tell us what happened and we'll take a look.",
  widgetSubmitLabel: "Send report",
  widgetSuccessMessage: "Thanks — we're on it.",
  widgetAccent: "#e05104",
  widgetAskEmail: true,
})

Everything together

A complete setup, in one file:

"use client"
import { useEffect } from "react"
import { init, initClickTracking, initPageTracking } from "@adtivity/adtivity-sdk"
import { SessionReplay } from "@adtivity/adtivity-sdk/session-replay"
import { initErrorTracking } from "@adtivity/adtivity-sdk/errors"

const API_KEY = process.env.NEXT_PUBLIC_ADTIVITY_API_KEY!

export function Analytics() {
  useEffect(() => {
    init({ apiKey: API_KEY })
    initPageTracking()
    initClickTracking({ trackAllButtons: true })

    initErrorTracking({ apiKey: API_KEY })

    const replay = new SessionReplay({ apiKey: API_KEY, sampleRate: 0.5 })
    replay.start()
    return () => replay.stop()
  }, [])

  return null
}

That covers everything anonymous. The last piece is telling Adtivity who each visitor is — call identify() wherever your app learns that, and resetIdentity() on sign-out:

import { identify, resetIdentity } from "@adtivity/adtivity-sdk"

// wherever your sign-in succeeds
identify(user.id, {
  email: user.email,   // without this, every screen says "Anonymous"
  name:  user.name,
  plan:  user.plan,
})

// wherever your sign-out happens
resetIdentity()

At-Risk Users

Adtivity scores every one of your end users on how likely they are to stop coming back, and shows you the page they were last on before they went quiet. It answers two questions: who is falling off, and where they fall off.

How the score works

Each person is measured against their own visit rhythm rather than a fixed cut-off. Three weeks of silence is a strong signal for someone who used to show up daily and means nothing at all for someone who shows up monthly — a single threshold gets one of those wrong.

The score from 0 to 100 blends five signals, each shown on screen in plain language:

Segments — and which ones to act on

Users are grouped by what to do about them, not by how far gone they are. The important split is at the top: two people can score identically while being very differently recoverable.

The ranked list is ordered by risk weighted against how engaged someone was, so a long-standing regular going quiet appears above a casual visitor with the same raw score.

How accurate is it?

We validated the scoring by running it against real production data as of a past date — using only what was known then — and checking who actually came back over the following 45 days:

A user scored LOW was about 6.5x more likely to return than one scored HIGH or above. Every person also carries a confidence label — someone with two days of history is a guess, and the dashboard says so rather than hiding it behind a decisive-looking number.

Drop-off Map

The second half of the screen answers where. For every page, it shows what share of the people who reached it never went any further — their journey ended there.

A high abandon rate on a page with real volume is a leak worth fixing. Pages seen by fewer than five people are excluded, because a 100% abandon rate over three visitors is noise. Ranking is by at-risk exits rather than raw traffic — otherwise your home page wins every time and tells you nothing.

Following one person

Click any user to open their full history: every visit, the pages in each one, the errors they hit, and their exit path — the last few pages before they went quiet, newest first. Where a session replay exists for a visit, you can watch it back from that same panel.

Company Churn Risk

Separate from the per-user screen above, Churn Risk scores your business as a whole — usage trend against revenue churn — and writes up what it sees. Use At-Risk Users to find people to email; use Churn Risk to judge whether the business is trending the wrong way.

Churn Risk also takes a comparison window and a free-text context box, so you can tell it things the database cannot know — a pricing change, an outage, a planned migration — before it reads a deliberate drop as churn.

Events

An event is a single thing that happened — a page view, a click, an identify call, a wallet connect. Every event captured by the SDK gets enriched with the auto-captured context above and lands in your Adtivity workspace ready to query.

You don't compose events manually. The SDK produces them from data attributes on your markup and from the init* functions you call once at startup.

Companies

A company is the workspace that owns your data. One Adtivity account can have multiple companies — useful if you ship more than one product, or want a clean split between staging and production. Each company has its own API key and dashboard.

Set up a new company from Settings → Companies → New.

Users

A user is anyone whose journey Adtivity has stitched together. On first visit they exist as an anonymous ID; the moment you call identify() with a userId, email, or wallet address, anonymous activity gets merged into the known user record. See Identity for how to wire that up.

Lifecycle

Adtivity automatically classifies users by where they sit in your funnel — visitor, signup, activated, paying, churned — by reading the events you're already sending. The Lifecycle Chart on your dashboard is the canonical view; the same buckets are queryable through the MCP server.

Stripe Integration

Connect Stripe from Settings → Connections — about 90 seconds. Once connected, MRR, ARR and churn auto-populate in your dashboard and become queryable through the MCP server. No manual event tracking required for revenue.

Paystack Integration

Processing payments in Africa? Connect Paystack the same way — Settings → Connections. Stripe and Paystack can be active in the same workspace; revenue from both is unified into a single MRR view.

Wallet Monitoring — No SDK Required

You don't need the SDK to track on-chain activity. Register any wallet address in the Web3 Wallets section of your company dashboard and Adtivity monitors it at the backend level — no MetaMask, no ethers.js, no SDK integration.

Privacy & Consent

Call setConsent(false) when a user opts out. This stops all future event tracking, flushes and clears the event queue, and removes persisted events from localStorage. Call setConsent(true) to re-enable.

import { setConsent } from "@adtivity/adtivity-sdk";

// User opts out
setConsent(false);

// User opts back in
setConsent(true);

You can also start with all tracking off by passing collectData: false to init().

Runtime Configuration

Swap the API key or backend URL after init — useful when users switch workspaces or when you point to a different environment at runtime.

import { setApiKey, setBaseUrl } from "@adtivity/adtivity-sdk";

// After user logs into a different workspace
setApiKey("new-api-key");

// Point to a different backend
setBaseUrl("https://your-custom-backend.com");

React Native

The SDK is React Native compatible. Because AsyncStorage reads are asynchronous, call waitUntilReady() before tracking to ensure the anonymous ID and session ID have loaded from storage.

import { init, waitUntilReady, trackEvent, setWallet } from "@adtivity/adtivity-sdk";

init({ apiKey: "your-api-key" });

await waitUntilReady();   // wait for AsyncStorage IDs to load

trackEvent("App Opened");
setWallet("0xabc...", "1");

REST API Coming soon

A public REST surface is on the roadmap for teams that want to read Adtivity data outside of the dashboard or the MCP server — for internal tools, custom dashboards, or scheduled exports. Endpoints, auth model, and rate limits will be documented here once it lands.

Until then, the MCP server is the supported way to query your data programmatically.

SDK Reference

Quick index of every public function in @adtivity/adtivity-sdk:

Event Schema

Every event the SDK produces ships with the same envelope of auto-captured fields. The full reference is in Auto-Captured Data; the short version:

All events are sent as a JSON array to POST /sdk/event with an X-API-Key header. Top-level fields (wallet_address, chain_id, transaction_hash, contract_address, country, region, city, ip_address) are always promoted out of properties. Null and empty-string values are omitted.

{
  "type":              "track",
  "eventName":         "Token Swap",
  "timestamp":         "2025-06-23T12:00:00.000Z",

  "anonymous_id":      "uuid-v4",
  "session_id":        "uuid-v4",
  "user_id":           "user_abc123",

  "wallet_address":    "0xabc...def",
  "chain_id":          "1",

  "transaction_hash":  "0xdef...789",
  "contract_address":  "0x123...456",

  "country":           "US",
  "region":            "California",
  "city":             "San Francisco",
  "ip_address":        "203.0.113.1",

  "properties": {
    "url":       "https://app.example.com/swap",
    "referrer":  "https://app.example.com/",
    "userAgent": "Mozilla/5.0...",
    "amount":    "100",
    "token":     "USDC"
  }
}

Best practices

A few things worth doing on day one:

• Name events for humans, not machines. Your dashboard, your team, and your AI all read these.
• Identify users early. Call identify() the moment auth resolves so the anonymous → known stitch happens cleanly.
• Turn on debug: true locally. You'll see every event in the console while you wire things up.
• Keep the public key public, the server key private. They're separate by design.

Next: Connect MCP → · Plug in Stripe → · Web3 identity →