> ## 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.
# Tappd Web SDK Configuration Options and Best Practices
> Complete reference for every configuration option accepted by the Tappd Web SDK, including defaults, types, and environment-based setup patterns.
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.
```javascript theme={null}
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 )
debug: false // Default
});
```
## Configuration reference
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](https://gotappd.com).
```javascript theme={null}
const tappd = new TappdSDK({
appId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
});
```
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.
```javascript theme={null}
const tappd = new TappdSDK({
appId: 'YOUR_APP_ID',
apiUrl: 'https://custom-domain.com/api/v1/sdk'
});
```
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.
```javascript theme={null}
// 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' });
```
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.
```javascript theme={null}
// Start a new session after 60 minutes of inactivity
const tappd = new TappdSDK({
appId: 'YOUR_APP_ID',
sessionTimeout: 60
});
```
When enabled, the SDK automatically listens for link clicks (`` 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.
```javascript theme={null}
// Auto-capture all link clicks and form submissions
const tappd = new TappdSDK({
appId: 'YOUR_APP_ID',
enableAutoCapture: 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.
```javascript theme={null}
// Disable all in-app messages
const tappd = new TappdSDK({
appId: 'YOUR_APP_ID',
enableInAppMessages: false
});
```
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.
```javascript theme={null}
// Fetch messages but control display manually
const tappd = new TappdSDK({
appId: 'YOUR_APP_ID',
enableInAppMessages: true,
autoDisplayMessages: false
});
```
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.
```javascript theme={null}
// Check for new messages every 60 seconds
const tappd = new TappdSDK({
appId: 'YOUR_APP_ID',
messagePollingInterval: 60
});
```
The `id` of a DOM element to render in-app messages into. If you don't set this, messages are appended directly to ``. Use a custom container to control exactly where messages appear in your layout — for example, inside a fixed header or notification area.
```html theme={null}
```
```javascript theme={null}
// Render messages inside a specific container
const tappd = new TappdSDK({
appId: 'YOUR_APP_ID',
messageContainerId: 'tappd-messages'
});
```
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.
```javascript theme={null}
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.
```javascript theme={null}
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.
```javascript theme={null}
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
Explore every method available on the `TappdSDK` instance.
Learn how to configure and display in-app messages.
See configuration options applied in real-world scenarios.