Configuration

Configure the Tappd Web SDK to match your application's needs.

Configuration Options

The SDK accepts a configuration object when initializing:

const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  apiUrl: 'https://sdk.gotappd.com/api/v1/sdk',
  autoTrack: true,
  sessionTimeout: 30,
  enableAutoCapture: false,
  enableInAppMessages: true,
  autoDisplayMessages: true,
  messagePollingInterval: 30,
  debug: false
});

Configuration Reference

Option	Type	Default	Required	Description
appId	string	-	Yes	Your App ID from the Tappd dashboard
apiUrl	string	https://sdk.gotappd.com/api/v1/sdk	No	Custom API endpoint URL
autoTrack	boolean	true	No	Automatically track page views on load and navigation
sessionTimeout	number	30	No	Session timeout in minutes (inactivity before new session)
enableAutoCapture	boolean	false	No	Automatically capture link clicks and form submissions
enableInAppMessages	boolean	true	No	Enable/disable in-app message rendering
autoDisplayMessages	boolean	true	No	Automatically fetch and display pending messages
messagePollingInterval	number	30	No	Interval in seconds for polling new messages
messageContainerId	string	undefined	No	Custom DOM container ID for messages
debug	boolean	false	No	Enable debug logging to console

Detailed Options

appId

Your unique App ID from the Tappd dashboard. This identifies your application and is required for all SDK operations.

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

apiUrl

Custom API endpoint URL. Only change this if you're using a self-hosted instance or custom domain.

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

autoTrack

Enable automatic page view tracking. When true, the SDK automatically tracks:

• Initial page load
• Page navigation (SPA support via History API)
• Browser back/forward navigation

// Enable auto-tracking (default)
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  autoTrack: true
});

// Disable auto-tracking (manual tracking only)
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  autoTrack: false
});

sessionTimeout

Session timeout in minutes. If the user is inactive for this duration, a new session starts automatically.

// 30 minute timeout (default)
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  sessionTimeout: 30
});

// 60 minute timeout
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  sessionTimeout: 60
});

enableAutoCapture

Automatically capture and track:

• Link clicks (<a> tags)
• Form submissions

// Enable auto-capture
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  enableAutoCapture: true
});

// Link clicks will automatically fire:
// tappd.track('link_click', { url: '...', text: '...' })

// Form submissions will automatically fire:
// tappd.track('form_submit', { formId: '...', formAction: '...' })

enableInAppMessages

Enable or disable in-app message rendering. When enabled, the SDK can fetch and display in-app messages (banners, popups, modals) created in your Tappd dashboard.

// Enable in-app messages (default)
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  enableInAppMessages: true
});

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

See also: In-App Messages Guide for detailed documentation.

autoDisplayMessages

Automatically fetch and display pending in-app messages when enabled. Requires enableInAppMessages to be true.

// Auto-display messages (default)
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  enableInAppMessages: true,
  autoDisplayMessages: true
});

// Manual message control only
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  enableInAppMessages: true,
  autoDisplayMessages: false
});

messagePollingInterval

Interval in seconds for polling new messages from the API. Only applies when autoDisplayMessages is enabled.

// Poll every 30 seconds (default)
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  messagePollingInterval: 30
});

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

messageContainerId

Custom DOM container ID where messages should be rendered. If not provided, messages are appended to document.body.

// Use custom container
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  messageContainerId: 'tappd-messages'
});

HTML:

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

debug

Enable debug logging. When true, the SDK logs all operations to the browser console.

const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  debug: true // See all SDK operations in console
});

// 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

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

const tappd = new TappdSDK({
  appId: process.env.VITE_TAPPD_APP_ID,
  apiUrl: process.env.VITE_TAPPD_API_URL || 'https://sdk.gotappd.com/api/v1/sdk',
  debug: isDevelopment, // Only debug in development
  autoTrack: true,
  sessionTimeout: 30
});

Multiple Environments

const config = {
  development: {
    appId: 'dev_app_id',
    apiUrl: 'https://dev.sdk.gotappd.com/api/v1/sdk',
    debug: true
  },
  staging: {
    appId: 'staging_app_id',
    apiUrl: 'https://staging.sdk.gotappd.com/api/v1/sdk',
    debug: true
  },
  production: {
    appId: 'prod_app_id',
    apiUrl: 'https://sdk.gotappd.com/api/v1/sdk',
    debug: false
  }
};

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

Best Practices

1. Always use environment variables for App ID in production
2. Enable debug mode only in development
3. Use autoTrack for most applications (simpler setup)
4. Set appropriate session timeout based on your user behavior patterns
5. Disable autoCapture if you want more control over what gets tracked

Next Steps

• API Reference - Learn about available methods
• Session Management - Understand session tracking behavior
• Examples - See configuration in action