Get Started with the Tappd Web SDK: A Step-by-Step Guide

This guide walks you through integrating the Tappd Web SDK from scratch. By the end, you’ll have session tracking, user identification, custom event tracking, and page view recording running in your application.

Get your App ID

Every SDK call is tied to a Tappd app. Before you write any code, grab the App ID for the application you want to instrument.

Log in to your Tappd Dashboard.
Navigate to Settings → Apps.
Create a new app or select an existing one.
Copy the App ID — it looks like a1b2c3d4-e5f6-7890-abcd-ef1234567890.

Store your App ID in an environment variable (e.g. VITE_TAPPD_APP_ID or REACT_APP_TAPPD_APP_ID) rather than hard-coding it in source files. This makes it easy to use different IDs across dev, staging, and production.

Install the SDK

Choose the installation method that matches your project setup.

<!-- Add before the closing </body> tag -->
<script src="https://cdn.gotappd.com/web-sdk/v1/tappd-sdk.min.js"></script>

The CDN build exposes the SDK as TappdSDK.TappdSDK on the global window object. The NPM build uses named exports, so you import TappdSDK directly.

Initialize the SDK

Call new TappdSDK(config) once when your application loads — not on every page render. Initializing the SDK starts a session and, if autoTrack is enabled, records the first page view immediately.

import { TappdSDK } from '@tappd/web-sdk';

const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  apiUrl: 'https://sdk.gotappd.com/api/v1/sdk', // Default  
  autoTrack: true,       // Auto-track page views (default: true)
  sessionTimeout: 30,    // Minutes of inactivity before a new session starts (default: 30)
  debug: false           // Set to true during development to see console logs
});

Replace YOUR_APP_ID with the ID you copied from the dashboard.

Identify users

Call tappd.identify() as soon as you know who the current user is — typically after login or signup. The SDK automatically merges any anonymous activity recorded before identification with the user’s profile.

await tappd.identify({
  external_id: 'user_123',       // Required: your unique user ID
  name: 'John Doe',
  email: 'john@example.com',
  phone: '+1234567890',
  // Add any custom attributes relevant to your app
  plan: 'premium',
  company: 'Acme Corp'
});

The external_id field is your application’s user identifier (for example, a UUID or any unique, stable ID from your system). The SDK generates and manages its own session-level identifier automatically — you don’t need to create or pass one.

Track events

Use tappd.track() to record any meaningful action in your application. Pass an event name and an optional properties object.

// Track a purchase
await tappd.track('purchase', {
  amount: 99.99,
  currency: 'USD',
  productId: 'prod_123'
});

// Track a button click
await tappd.track('button_click', {
  buttonId: 'signup',
  location: 'homepage'
});

Event names can be any string. Use consistent naming across your app — for example, snake_case — so your analytics data stays clean and queryable.

Track page views manually (optional)

When autoTrack is enabled (the default), the SDK records page views for you automatically, including client-side navigation in SPAs. If you disable autoTrack or need to record a page view at a specific moment, call tappd.trackPageView() directly.

// Track the current page URL
await tappd.trackPageView();

// Track a specific URL with additional properties
await tappd.trackPageView('https://example.com/pricing', {
  referrer: 'google.com',
  campaign: 'spring_promo'
});

Use trackPageView in frameworks where you control routing manually — for example, inside a route-change handler — to ensure every navigation is captured with the context you need.

Framework-specific setup

The SDK is framework-agnostic, but each framework has its own lifecycle conventions. Use the tab for your stack to see the recommended initialization pattern.

React
Vue.js
Next.js

Initialize the SDK inside a useEffect with an empty dependency array so it runs once after the component mounts. Store the instance on window (or in a React Context) so other components can access it without re-initializing.

import { useEffect } from 'react';
import { TappdSDK } from '@tappd/web-sdk';

function App() {
  useEffect(() => {
    const tappd = new TappdSDK({
      appId: process.env.REACT_APP_TAPPD_APP_ID,
      autoTrack: true
    });

    // Make the instance available globally or via Context
    window.tappd = tappd;
  }, []);

  const handlePurchase = async () => {
    await window.tappd.track('purchase', {
      amount: 99.99
    });
  };

  return <button onClick={handlePurchase}>Buy Now</button>;
}

export default App;

Initialize inside the onMounted lifecycle hook so the SDK starts after the component is attached to the DOM. Keep a reference in setup() and expose tracking helpers to your template.

import { onMounted, ref } from 'vue';
import { TappdSDK } from '@tappd/web-sdk';

export default {
  setup() {
    let tappd;

    onMounted(() => {
      tappd = new TappdSDK({
        appId: import.meta.env.VITE_TAPPD_APP_ID,
        autoTrack: true
      });
    });

    const trackEvent = async (eventName, properties) => {
      if (tappd) {
        await tappd.track(eventName, properties);
      }
    };

    return { trackEvent };
  }
};

In the App Router, initialize the SDK inside a useEffect in your root layout component. Return a cleanup function that calls tappd.reset() to clear state when the component unmounts.

'use client';

import { useEffect } from 'react';
import { TappdSDK } from '@tappd/web-sdk';

export default function RootLayout({ children }) {
  useEffect(() => {
    const tappd = new TappdSDK({
      appId: process.env.NEXT_PUBLIC_TAPPD_APP_ID,
      autoTrack: true
    });

    window.tappd = tappd;

    // Clean up on unmount
    return () => {
      tappd.reset();
    };
  }, []);

  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Mark your layout component with 'use client' — the SDK runs in the browser and cannot be used in Server Components.

Verify your installation

Enable debug: true during development to confirm the SDK initialized correctly. Open your browser’s developer console and look for log output like the following:

const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  debug: true
});

[Tappd SDK] Initialized with App ID: a1b2c3d4...
[Tappd SDK] New session started: sess_abc123
[Tappd SDK] Event tracked: page_view

Once you see these messages, the SDK is working correctly. Switch debug back to false before deploying to production.

Next steps

Configuration Reference

Fine-tune session timeouts, message polling, auto-capture, and more.

API Reference

Explore every method available on the TappdSDK instance.

In-App Messages

Display banners, popups, and modals triggered by user behavior.

Examples

Browse real-world code samples for common use cases.

​Framework-specific setup

​Verify your installation

​Next steps

Configuration Reference

API Reference

In-App Messages

Examples

Framework-specific setup

Verify your installation

Next steps