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

# Get Started with the Tappd Mobile SDK in React Native

> Install the Tappd Mobile SDK, initialize it in your React Native app, and start tracking users, screens, and custom events in just minutes.

This guide walks you through installing and configuring the Tappd Mobile SDK from scratch. By the end, your React Native app will be tracking app lifecycle events, screen views, and custom events — with users identified by their account data.

## Prerequisites

Before you begin, make sure you have the following ready:

* A [Tappd account](https://gotappd.com) and your App ID
* A React Native project running version **0.60 or later**
* **iOS**: Xcode and CocoaPods installed
* **Android**: Android Studio installed

<Steps>
  ### Get Your App ID

  Your App ID connects the SDK to your Tappd project. Retrieve it from the dashboard before writing any code.

  1. Log into your [Tappd Dashboard](https://gotappd.com)
  2. Navigate to **Settings → Apps**
  3. Create a new mobile app or select an existing one
  4. Copy your **App ID** — it looks like `a1b2c3d4-e5f6-7890-abcd-ef1234567890`

  <Tip>
    Keep your App ID close by — you'll need it in the next step. Treat it like an API key and avoid committing it directly to source control. Use environment variables in production.
  </Tip>

  ### Install Dependencies

  Install the SDK package and its required peer dependency.

  <CodeGroup>
    ```bash npm theme={null}
    npm install @tappd/mobile-sdk @react-native-async-storage/async-storage
    ```

    ```bash yarn theme={null}
    yarn add @tappd/mobile-sdk @react-native-async-storage/async-storage
    ```
  </CodeGroup>

  Optionally, install `react-native-device-info` to capture richer device metadata such as device model and app version. This package is recommended but not required.

  <CodeGroup>
    ```bash npm theme={null}
    npm install react-native-device-info
    ```

    ```bash yarn theme={null}
    yarn add react-native-device-info
    ```
  </CodeGroup>

  For iOS, link the native dependencies by running CocoaPods after installing.

  ```bash theme={null}
  cd ios && pod install && cd ..
  ```

  <Note>
    Android requires no additional linking. The SDK works out of the box on Android after the npm install.
  </Note>

  ### Initialize the SDK

  Initialize the SDK at the top level of your app, before the root component mounts. Open `App.js` or `App.tsx` and add the following.

  ```javascript theme={null}
  import React from 'react';
  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,
    enableAutoScreenTracking: true,
    debug: false
  });

  // Make it available throughout your app
  global.tappd = tappd;

  function App() {
    return (
      // Your app content
    );
  }

  export default App;
  ```

  Replace `YOUR_APP_ID` with the App ID you copied from the dashboard. See the [Configuration reference](/mobile-sdk/configuration) for a full breakdown of every available option.

  ### Identify Users

  Call `identify()` whenever a user logs in or signs up so that all future events are linked to their profile.

  ```javascript theme={null}
  async function handleLogin(userId, email, name) {
    await tappd.identify({
      external_id: userId,  // Recommended: your own user ID
      name: name,
      email: email,
      phone: '+1234567890',
      // Any additional attributes you want to store
      plan: 'premium',
      age: 28
    });
  }
  ```

  At least one identifier is required — `external_id`, `email`, `phone`, or `alias`. Using `external_id` (your own user ID from your auth system) is recommended for the most reliable customer matching. The SDK handles its own internal tracking identifier automatically.

  <Note>
    After `identify()` is called, all subsequent `track()` and `trackScreen()` calls are automatically associated with that user. You only need to call `identify()` once per login.
  </Note>

  ### Track Screens

  Record screen views so you can see which parts of your app users visit most. Use `useFocusEffect` from React Navigation to fire a screen event each time a screen comes into focus.

  ```javascript theme={null}
  import React from 'react';
  import { View } from 'react-native';
  import { useFocusEffect } from '@react-navigation/native';

  function HomeScreen() {
    useFocusEffect(
      React.useCallback(() => {
        global.tappd.trackScreen('HomeScreen', {
          category: 'main',
          section: 'dashboard'
        });
      }, [])
    );

    return <View>{/* screen content */}</View>;
  }
  ```

  When `autoTrack: true` is set in your config, the SDK also automatically records these app lifecycle events without any additional code:

  | Event            | Triggered When                      |
  | ---------------- | ----------------------------------- |
  | `app.opened`     | The app is launched                 |
  | `app.foreground` | The app returns from the background |
  | `app.background` | The app moves to the background     |
  | `app.closed`     | The app is closed via `cleanup()`   |

  ### Track Custom Events

  Fire custom events to capture any user action that matters to your business — purchases, button clicks, form completions, and more.

  ```javascript theme={null}
  // Track a purchase
  await global.tappd.track('purchase', {
    amount: 99.99,
    currency: 'USD',
    productId: 'prod_123'
  });

  // Track a button click
  await global.tappd.track('button_click', {
    buttonId: 'signup',
    location: 'onboarding'
  });
  ```

  Pass any JSON-serializable properties as the second argument. These properties appear in your Tappd dashboard alongside each event.
</Steps>

## Project Setup Patterns

Choose the pattern that best fits how your project is structured. All three approaches produce the same result — pick the one that matches your team's conventions.

<Tabs>
  <Tab title="Context Provider (Recommended)">
    The Context pattern gives every component in your tree clean access to the SDK instance without relying on globals. Create a dedicated context file and wrap your app in the provider.

    ```javascript theme={null}
    // contexts/TappdContext.js
    import React, { createContext, useContext } from 'react';
    import TappdSDK from '@tappd/mobile-sdk';

    const TappdContext = createContext(null);

    export function TappdProvider({ children }) {
      const tappd = new TappdSDK({
        appId: 'YOUR_APP_ID',
        autoTrack: true,
        sessionTimeout: 30
      });

      return (
        <TappdContext.Provider value={tappd}>
          {children}
        </TappdContext.Provider>
      );
    }

    export function useTappd() {
      return useContext(TappdContext);
    }
    ```

    Then wrap your root component with `TappdProvider` in `App.js`.

    ```javascript theme={null}
    // App.js
    import { TappdProvider } from './contexts/TappdContext';

    function App() {
      return (
        <TappdProvider>
          {/* Your app */}
        </TappdProvider>
      );
    }

    export default App;
    ```

    Access the SDK in any component using the `useTappd` hook.

    ```javascript theme={null}
    import { useTappd } from './contexts/TappdContext';

    function CheckoutScreen() {
      const tappd = useTappd();

      const handlePurchase = async () => {
        await tappd.track('purchase', { amount: 49.99, currency: 'USD' });
      };

      return <Button onPress={handlePurchase}>Buy Now</Button>;
    }
    ```
  </Tab>

  <Tab title="Custom Hook">
    Create a dedicated hook that initializes the SDK once and returns the same instance on every render.

    ```javascript theme={null}
    // hooks/useTappd.js
    import { useState } from 'react';
    import TappdSDK from '@tappd/mobile-sdk';

    export function useTappd() {
      const [tappd] = useState(() => {
        return new TappdSDK({
          appId: 'YOUR_APP_ID',
          autoTrack: true,
          sessionTimeout: 30
        });
      });

      return tappd;
    }
    ```

    Import and call the hook in any screen or component.

    ```javascript theme={null}
    import { useTappd } from './hooks/useTappd';

    function ProfileScreen() {
      const tappd = useTappd();

      const handleUpdate = async () => {
        await tappd.track('profile_updated', { field: 'email' });
      };

      return <Button onPress={handleUpdate}>Save Changes</Button>;
    }
    ```
  </Tab>

  <Tab title="Global Variable">
    Assign the SDK instance to `global.tappd` at app startup for straightforward access anywhere without imports or hooks. This is the quickest approach for smaller projects.

    ```javascript theme={null}
    // App.js
    import TappdSDK from '@tappd/mobile-sdk';

    global.tappd = new TappdSDK({
      appId: 'YOUR_APP_ID',
      autoTrack: true,
      sessionTimeout: 30
    });

    function App() {
      return (
        // Your app
      );
    }

    export default App;
    ```

    Access the instance directly in any file without importing anything.

    ```javascript theme={null}
    function SettingsScreen() {
      const handleLogout = async () => {
        await global.tappd.track('user_logged_out');
      };

      return <Button onPress={handleLogout}>Log Out</Button>;
    }
    ```
  </Tab>
</Tabs>

## Verify Installation

Enable `debug: true` when you first set up the SDK to confirm everything is working. With debug mode on, the SDK prints detailed logs to your React Native console.

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

Open your Metro bundler console or device logs and look for output like this:

```text theme={null}
[Tappd SDK] Initialized with App ID: a1b2c3d4...
[Tappd SDK] New session started: sess_abc123
[Tappd SDK] Event tracked: app.opened
```

<Warning>
  Disable `debug: true` before releasing to production. Debug logging can expose sensitive data in device logs and may affect performance.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="sliders" href="/mobile-sdk/configuration">
    Customize every SDK option — session timeouts, polling intervals, in-app messages, and environment-based config.
  </Card>

  <Card title="React Navigation" icon="map" href="/mobile-sdk/react-navigation">
    Integrate automatic screen tracking with your React Navigation stack.
  </Card>

  <Card title="Push Notifications" icon="bell" href="/mobile-sdk/push-notifications">
    Register FCM and APNs push tokens and manage notification subscriptions.
  </Card>

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