Tappd Mobile SDK Configuration Reference and Options

The Tappd Mobile SDK accepts a configuration object when you call new TappdSDK(config). Every option except appId is optional and ships with a sensible default. This page covers every available option, explains what it controls, and shows patterns for managing configuration across different environments.

Full Configuration Example

Use this as a starting point and remove any options you don’t need to override.

import TappdSDK from '@tappd/mobile-sdk';

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

Configuration Reference

appId

string

required

Your unique App ID from the Tappd dashboard. This identifies your application and is required for every SDK operation. Retrieve it from 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. Leave this at the default unless you’re using a self-hosted 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"

When true, the SDK automatically records app lifecycle events using React Native’s AppState API. Disable this only if you want to fire lifecycle events manually.The following events are tracked automatically when autoTrack is enabled:

Event	Triggered When
`app.opened`	The app is launched from a cold start
`app.foreground`	The app returns from the background
`app.background`	The app moves to the background
`app.closed`	The app closes, triggered by `cleanup()`

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

sessionTimeout

number

default:"30"

The number of minutes of inactivity before the SDK starts a new session when the app returns to the foreground. Adjust this to reflect your app’s typical usage patterns — a longer timeout suits apps used in extended bursts, while a shorter timeout suits apps opened frequently for short tasks.

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

enableAutoScreenTracking

boolean

default:"true"

Enables automatic screen view tracking. This option does not track screens on its own — it must be paired with a manual trackScreen() call inside each screen component (using useFocusEffect from React Navigation, for example). See the React Navigation integration guide for the full setup.

// Disable automatic screen tracking
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  enableAutoScreenTracking: false
});

enableInAppMessages

boolean

default:"true"

Controls whether the SDK fetches and renders in-app messages (banners, popups, and modals) created in your Tappd dashboard. When enabled, you must also call setMessageRenderCallback() to provide a React Native component that renders the message payload.

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

See the In-App Messages guide for instructions on setting up setMessageRenderCallback().

autoDisplayMessages

boolean

default:"true"

When true, the SDK automatically polls for pending in-app messages and displays them without any additional code. Set this to false if you want full manual control over when messages appear — for example, to display them only after specific user actions. Requires enableInAppMessages: true to have any effect.

// Take manual control of message display
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  enableInAppMessages: true,
  autoDisplayMessages: false
});

messagePollingInterval

number

default:"30"

The number of seconds between polls for new in-app messages. Only applies when autoDisplayMessages is true. Increase this value to reduce network activity in battery-sensitive contexts; decrease it if your messages need to appear quickly after they’re triggered.

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

debug

boolean

default:"false"

When true, the SDK logs every operation to the console using React Native’s logging APIs. Use this during development to verify events are firing correctly and to diagnose unexpected behavior.

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

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

Always disable debug mode in production builds. Setting debug: __DEV__ ensures logs are automatically suppressed in release builds.

Environment-Based Configuration

Development vs. Production

React Native exposes the __DEV__ boolean globally. Use it to toggle debug logging automatically based on the current build type.

import TappdSDK from '@tappd/mobile-sdk';

const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  apiUrl: 'https://sdk.gotappd.com/api/v1/sdk',
  autoTrack: true,
  sessionTimeout: 30,
  debug: __DEV__  // true in development, false in production builds
});

Multiple Environments

If your project uses separate App IDs for development, staging, and production, define a config map and select the right entry based on __DEV__.

import TappdSDK from '@tappd/mobile-sdk';

const configs = {
  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 = __DEV__ ? 'development' : 'production';

const tappd = new TappdSDK(configs[env]);

Using Environment Variables

Keep your App ID out of source control by loading it from environment variables with react-native-config. 1. Create your .env file at the project root:

TAPPD_APP_ID=your_app_id_here
TAPPD_API_URL=https://sdk.gotappd.com/api/v1/sdk

2. Load the variables in your app:

import Config from 'react-native-config';
import TappdSDK from '@tappd/mobile-sdk';

const tappd = new TappdSDK({
  appId: Config.TAPPD_APP_ID,
  apiUrl: Config.TAPPD_API_URL,
  debug: __DEV__
});

Add .env to your .gitignore to avoid committing secrets. Provide a .env.example file with placeholder values so teammates know which variables to set.

Best Practices

Follow these guidelines to get the most reliable behavior from the SDK across all environments:

Store App ID in environment variables — never hard-code it directly in source files that are committed to version control.
Set debug: __DEV__ — this is the simplest way to ensure debug logs are active during development and silent in production without any manual toggling.
Enable autoTrack: true for most apps — it covers lifecycle events automatically and reduces the amount of instrumentation code you need to maintain.
Tune sessionTimeout to match your users’ habits — if your app is typically used in short bursts throughout the day, a 15-minute timeout gives you more accurate session counts than the default 30 minutes.
Call cleanup() when the app closes — this fires the app.closed event and flushes any pending data, ensuring your analytics are complete even for users who close the app abruptly.

Next Steps

API Reference

Browse every method available on the TappdSDK instance with full parameter details.

Push Notifications

Configure FCM and APNs push token registration and subscription management.

In-App Messages

Set up render callbacks to display banners, popups, and modals from your dashboard.

Examples

See real-world configuration patterns and common integration scenarios.

​Full Configuration Example

​Configuration Reference

​Environment-Based Configuration

​Development vs. Production

​Multiple Environments

​Using Environment Variables

​Best Practices

​Next Steps

API Reference

Push Notifications

In-App Messages

Examples

Full Configuration Example

Configuration Reference

Environment-Based Configuration

Development vs. Production

Multiple Environments

Using Environment Variables

Best Practices

Next Steps