> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tappd.io/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Install the Tappd Web SDK, initialize it with your App ID, identify users, track custom events, and record page views — all in under 10 minutes.

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.

<Steps>
  <Step title="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.

    1. Log in to your [Tappd Dashboard](https://gotappd.com).
    2. Navigate to **Settings → Apps**.
    3. Create a new app or select an existing one.
    4. Copy the **App ID** — it looks like `a1b2c3d4-e5f6-7890-abcd-ef1234567890`.

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="Install the SDK">
    Choose the installation method that matches your project setup.

    <CodeGroup>
      ```html CDN theme={null}
      <!-- Add before the closing </body> tag -->
      <script src="https://cdn.gotappd.com/web-sdk/v1/tappd-sdk.min.js"></script>
      ```

      ```bash NPM theme={null}
      npm install @tappd/web-sdk
      ```

      ```javascript ES Module theme={null}
      import { TappdSDK } from '@tappd/web-sdk';
      ```

      ```javascript CommonJS theme={null}
      const { TappdSDK } = require('@tappd/web-sdk');
      ```
    </CodeGroup>

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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.

    ```javascript theme={null}
    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.
  </Step>

  <Step title="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.

    ```javascript theme={null}
    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'
    });
    ```

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Track events">
    Use `tappd.track()` to record any meaningful action in your application. Pass an event name and an optional properties object.

    ```javascript theme={null}
    // 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.
  </Step>

  <Step title="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.

    ```javascript theme={null}
    // 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'
    });
    ```

    <Tip>
      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.
    </Tip>
  </Step>
</Steps>

## 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.

<Tabs>
  <Tab title="React">
    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.

    ```javascript theme={null}
    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;
    ```
  </Tab>

  <Tab title="Vue.js">
    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.

    ```javascript theme={null}
    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 };
      }
    };
    ```
  </Tab>

  <Tab title="Next.js">
    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.

    ```javascript theme={null}
    '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>
      );
    }
    ```

    <Note>
      Mark your layout component with `'use client'` — the SDK runs in the browser and cannot be used in Server Components.
    </Note>
  </Tab>
</Tabs>

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

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

```text theme={null}
[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

<CardGroup cols={2}>
  <Card title="Configuration Reference" icon="sliders" href="/web-sdk/configuration">
    Fine-tune session timeouts, message polling, auto-capture, and more.
  </Card>

  <Card title="API Reference" icon="code" href="/web-sdk/api-reference">
    Explore every method available on the `TappdSDK` instance.
  </Card>

  <Card title="In-App Messages" icon="comment" href="/web-sdk/in-app-messages">
    Display banners, popups, and modals triggered by user behavior.
  </Card>

  <Card title="Examples" icon="book-open" href="/web-sdk/examples">
    Browse real-world code samples for common use cases.
  </Card>
</CardGroup>