Adtivity SDK Documentation

Basic Setup

Initialize the SDK in your application's root component (e.g., _app.tsx or layout.tsx for Next.js).

import {
  init,
  initClickTracking,
  initLocationTracking,
  initPageTracking,
} 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

Data Attributes for Tracking

Add data attributes to your HTML elements to automatically track user interactions.

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

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

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

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

Auto-Captured Element Data

The SDK automatically captures these properties from tracked elements:

Automatic Page View Tracking

Once initialized with initPageTracking(), the SDK automatically tracks:

Auto-Captured Page Data

IP-Based Geolocation

When you call initLocationTracking(), the SDK automatically enriches all events with geolocation data based on the user's IP address.

Auto-Captured Location Data

User Identification

The SDK provides multiple ways to identify and track users across sessions.

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

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

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

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

Web3 Support

Built-in support for blockchain and Web3 applications.

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

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

Data Captured on Every Event

The SDK automatically enriches all events with contextual data to provide comprehensive analytics.

Time & Context Data

Location & Network Data

Best Practices