Tappd Web SDK Configuration Options and Best Practices

When you call new TappdSDK(config), you pass a configuration object that controls how the SDK behaves — from session timeouts and page-view tracking to in-app message delivery and debug logging. Only appId is required; every other option has a sensible default you can override as needed.

Full configuration example

The snippet below shows every available option with its default value. Copy it as a starting point and remove any options you don’t need to change.

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

const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',                               // Required
  apiUrl: 'https://sdk.gotappd.com/api/v1/sdk',       // Default
  autoTrack: true,                                    // Default
  sessionTimeout: 30,                                 // Default (minutes)
  enableAutoCapture: false,                           // Default
  enableInAppMessages: true,                          // Default
  autoDisplayMessages: true,                          // Default
  messagePollingInterval: 30,                         // Default (seconds)
  messageContainerId: undefined,                      // Default (appends to <body>)
  debug: false                                        // Default
});

Configuration reference

appId

string

required

Your unique App ID from the Tappd dashboard. This identifies your application and is required for every SDK operation. Find it under Settings → Apps in your Tappd Dashboard.

const tappd = new TappdSDK({
  appId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
});

apiUrl

string

default:"https://sdk.gotappd.com/api/v1/sdk"

The API endpoint the SDK sends data to. You only need to change this if you’re using a self-hosted Tappd instance or a custom domain.

const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  apiUrl: 'https://custom-domain.com/api/v1/sdk'
});

autoTrack

boolean

default:"true"

Automatically records page views on the initial load and on every client-side navigation. This includes History API changes (push/pop state), which means single-page applications built with React Router, Vue Router, and similar libraries are tracked without any extra setup.Set this to false only if you want to call tappd.trackPageView() manually on every route change.

// Disable auto-tracking to control page views manually
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  autoTrack: false
});

// Then record page views yourself on each navigation
await tappd.trackPageView('/dashboard', { referrer: '/home' });

sessionTimeout

number

default:"30"

The number of minutes of user inactivity that triggers a new session. After the timeout elapses, the next user action starts a fresh session. Adjust this to match how your users typically interact with your application — a content site might use a longer timeout, while a transactional app might use a shorter one.

// Start a new session after 60 minutes of inactivity
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  sessionTimeout: 60
});

enableAutoCapture

boolean

default:"false"

When enabled, the SDK automatically listens for link clicks (<a> tags) and form submissions and records them as events — no manual track() calls needed. Link clicks fire a link_click event; form submissions fire a form_submit event, both with relevant metadata attached.Leave this disabled if you prefer to track interactions explicitly, which gives you more control over the event names and properties you capture.

// Auto-capture all link clicks and form submissions
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  enableAutoCapture: true
});

enableInAppMessages

boolean

default:"true"

Enables the in-app messaging system, which lets you fetch and display banners, popups, and modals created in the Tappd dashboard. Set this to false to disable all in-app message functionality globally, regardless of other message-related settings.

// Disable all in-app messages
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  enableInAppMessages: false
});

autoDisplayMessages

boolean

default:"true"

When true, the SDK automatically fetches pending in-app messages from the API and displays any that match the current user’s targeting rules. Requires enableInAppMessages to also be true.Set this to false if you want to control when messages appear — for example, only showing them on certain pages or after specific events.

// Fetch messages but control display manually
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  enableInAppMessages: true,
  autoDisplayMessages: false
});

messagePollingInterval

number

default:"30"

How often, in seconds, the SDK checks for new in-app messages. Only applies when autoDisplayMessages is true. Lower values mean users see new messages sooner; higher values reduce API requests.

// Check for new messages every 60 seconds
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  messagePollingInterval: 60
});

messageContainerId

string

The id of a DOM element to render in-app messages into. If you don’t set this, messages are appended directly to <body>. Use a custom container to control exactly where messages appear in your layout — for example, inside a fixed header or notification area.

<!-- HTML -->
<div id="tappd-messages"></div>

// Render messages inside a specific container
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  messageContainerId: 'tappd-messages'
});

debug

boolean

default:"false"

Enables verbose logging to the browser console. When true, the SDK logs every operation — initialization, session events, tracked events, identified users, and message fetches — prefixed with [Tappd SDK].Always set this to false in production to keep your console output clean.

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

// Console output:
// [Tappd SDK] Initialized with App ID: a1b2c3d4...
// [Tappd SDK] New session started: sess_abc123
// [Tappd SDK] Event tracked: purchase
// [Tappd SDK] Customer identified: user_123

Environment-based configuration

Development vs. production

Keep your development and production configurations separate using environment variables and a NODE_ENV check. This pattern enables debug logging locally without any risk of enabling it in production.

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

const isDevelopment = process.env.NODE_ENV === 'development';

const tappd = new TappdSDK({
  appId: process.env.VITE_TAPPD_APP_ID,           // Vite projects
  // appId: process.env.REACT_APP_TAPPD_APP_ID,  // Create React App projects
  apiUrl: process.env.VITE_TAPPD_API_URL || 'https://sdk.gotappd.com/api/v1/sdk',
  debug: isDevelopment,
  autoTrack: true,
  sessionTimeout: 30
});

Multiple environments

If you maintain separate Tappd apps for development, staging, and production, use an environment-keyed config object to switch between them automatically.

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

const configs = {
  development: {
    appId: process.env.VITE_TAPPD_APP_ID_DEV,
    apiUrl: 'https://sdk.gotappd.com/api/v1/sdk',
    debug: true
  },
  staging: {
    appId: process.env.VITE_TAPPD_APP_ID_STAGING,
    apiUrl: 'https://sdk.gotappd.com/api/v1/sdk',
    debug: true
  },
  production: {
    appId: process.env.VITE_TAPPD_APP_ID_PROD,
    apiUrl: 'https://sdk.gotappd.com/api/v1/sdk',
    debug: false
  }
};

const env = process.env.NODE_ENV || 'development';
const tappd = new TappdSDK(configs[env]);

Common environment variable names

Build tool	Variable format
Vite	`VITE_TAPPD_APP_ID`
Create React App	`REACT_APP_TAPPD_APP_ID`
Next.js	`NEXT_PUBLIC_TAPPD_APP_ID`
Generic Node.js	`TAPPD_APP_ID`

Never commit App IDs or API keys directly in your source code. Always read them from environment variables, and make sure your .env files containing real credentials are in .gitignore.

Best practices

Follow these guidelines to get the most reliable and maintainable SDK integration:

Use environment variables for your App ID in production. This prevents accidental exposure of credentials in source control and makes rotating IDs straightforward.
Enable debug only in development. Debug logging writes detailed output to the console, which is useful during integration but noisy in production.
Leave autoTrack enabled for most applications. It gives you page-view data immediately with zero extra code, including in SPAs that use client-side routing.
Set sessionTimeout based on how your users actually behave. A short timeout (15–20 min) suits transactional or task-focused apps; a longer timeout (45–60 min) suits content or research-heavy apps.
Keep enableAutoCapture disabled unless you need it. Manual tracking calls give you precise control over event names and properties, which keeps your analytics data clean and meaningful.

Next steps

API Reference

Explore every method available on the TappdSDK instance.

In-App Messages

Learn how to configure and display in-app messages.

Examples

See configuration options applied in real-world scenarios.

​Full configuration example

​Configuration reference

​Environment-based configuration

​Development vs. production

​Multiple environments

​Common environment variable names

​Best practices

​Next steps

API Reference

In-App Messages

Examples

Full configuration example

Configuration reference

Environment-based configuration

Development vs. production

Multiple environments

Common environment variable names

Best practices

Next steps