> ## 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 Mobile SDK Configuration Reference and Options

> Configure the Tappd React Native SDK with options for session management, screen tracking, in-app messages, debug logging, and environment variables.

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.

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

<ParamField path="appId" type="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](https://gotappd.com).

  ```javascript theme={null}
  const tappd = new TappdSDK({
    appId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
  });
  ```
</ParamField>

<ParamField path="apiUrl" type="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.

  ```javascript theme={null}
  const tappd = new TappdSDK({
    appId: 'YOUR_APP_ID',
    apiUrl: 'https://custom-domain.com/api/v1/sdk'
  });
  ```
</ParamField>

<ParamField path="autoTrack" type="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()` |

  ```javascript theme={null}
  // Disable auto lifecycle tracking
  const tappd = new TappdSDK({
    appId: 'YOUR_APP_ID',
    autoTrack: false
  });
  ```
</ParamField>

<ParamField path="sessionTimeout" type="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.

  ```javascript theme={null}
  // Start a new session after 60 minutes of inactivity
  const tappd = new TappdSDK({
    appId: 'YOUR_APP_ID',
    sessionTimeout: 60
  });
  ```
</ParamField>

<ParamField path="enableAutoScreenTracking" type="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](/mobile-sdk/react-navigation) for the full setup.

  ```javascript theme={null}
  // Disable automatic screen tracking
  const tappd = new TappdSDK({
    appId: 'YOUR_APP_ID',
    enableAutoScreenTracking: false
  });
  ```
</ParamField>

<ParamField path="enableInAppMessages" type="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.

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

  <Note>
    See the [In-App Messages guide](/mobile-sdk/in-app-messages) for instructions on setting up `setMessageRenderCallback()`.
  </Note>
</ParamField>

<ParamField path="autoDisplayMessages" type="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.

  ```javascript theme={null}
  // Take manual control of message display
  const tappd = new TappdSDK({
    appId: 'YOUR_APP_ID',
    enableInAppMessages: true,
    autoDisplayMessages: false
  });
  ```
</ParamField>

<ParamField path="messagePollingInterval" type="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.

  ```javascript theme={null}
  // Poll for new messages every 60 seconds
  const tappd = new TappdSDK({
    appId: 'YOUR_APP_ID',
    autoDisplayMessages: true,
    messagePollingInterval: 60
  });
  ```
</ParamField>

<ParamField path="debug" type="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.

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

  <Warning>
    Always disable debug mode in production builds. Setting `debug: __DEV__` ensures logs are automatically suppressed in release builds.
  </Warning>
</ParamField>

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

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

```javascript theme={null}
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:

```bash theme={null}
TAPPD_APP_ID=your_app_id_here
TAPPD_API_URL=https://sdk.gotappd.com/api/v1/sdk
```

**2. Load the variables** in your app:

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

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

## Best Practices

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

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/mobile-sdk/api-reference">
    Browse every method available on the TappdSDK instance with full parameter details.
  </Card>

  <Card title="Push Notifications" icon="bell" href="/mobile-sdk/push-notifications">
    Configure FCM and APNs push token registration and subscription management.
  </Card>

  <Card title="In-App Messages" icon="message" href="/mobile-sdk/in-app-messages">
    Set up render callbacks to display banners, popups, and modals from your dashboard.
  </Card>

  <Card title="Examples" icon="flask" href="/mobile-sdk/examples">
    See real-world configuration patterns and common integration scenarios.
  </Card>
</CardGroup>