Quickstart

Adtivity turns your product, payment and on-chain data into a signal you can read, share and act on. There are two ways in — pick the one that matches how you build.

Installation

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

npm install @adtivity/adtivity-sdk

The SDK is a browser-side library designed to live in your client bundle and tag events as users move through your product.

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();
  initLocationTracking();
}, []);

Configuration options

Click Tracking

Once initClickTracking() is running, Adtivity listens for any element marked with a data-adtivity-* attribute. No onClick handlers, no manual track() calls.

General click 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 automatically captures:

Each page view automatically includes the page URL, document title, referrer, and an ISO 8601 timestamp.

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.

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() with your own user ID. Anonymous activity from before sign-in is merged into the known user record automatically.

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

identify({
  userId: "user_12345",
  email:  "user@example.com",
  name:   "John Doe",
});

Web3 / wallet identity

When a user connects a wallet, pass the address and chain ID. Adtivity will tie wallet activity to the same anonymous user record.

identify({
  walletAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  chainId:       1, // Ethereum mainnet
});

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.

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.

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:

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.

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:

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 →