Get Started with the Tappd Mobile SDK in React Native

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 and your App ID
A React Native project running version 0.60 or later
iOS: Xcode and CocoaPods installed
Android: Android Studio installed

Get Your App ID

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

Log into your Tappd Dashboard

Navigate to Settings → Apps

Create a new mobile app or select an existing one

Copy your App ID — it looks like a1b2c3d4-e5f6-7890-abcd-ef1234567890

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.

Install Dependencies

Install the SDK package and its required peer dependency.

npm

npm install @tappd/mobile-sdk @react-native-async-storage/async-storage

yarn

yarn add @tappd/mobile-sdk @react-native-async-storage/async-storage

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.

npm

npm install react-native-device-info

yarn

yarn add react-native-device-info

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

cd ios && pod install && cd ..

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

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.

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

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.

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.

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.

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:

EventTriggered Whenapp.openedThe app is launchedapp.foregroundThe app returns from the backgroundapp.backgroundThe app moves to the backgroundapp.closedThe 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.

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

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.

Context Provider (Recommended)
Custom Hook
Global Variable

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.

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

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

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>;
}

Create a dedicated hook that initializes the SDK once and returns the same instance on every render.

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

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>;
}

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.

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

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

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

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.

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

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

[Tappd SDK] Initialized with App ID: a1b2c3d4...
[Tappd SDK] New session started: sess_abc123
[Tappd SDK] Event tracked: app.opened

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

Next Steps

Configuration

Customize every SDK option — session timeouts, polling intervals, in-app messages, and environment-based config.

React Navigation

Integrate automatic screen tracking with your React Navigation stack.

Push Notifications

API Reference

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

​Prerequisites

​Project Setup Patterns

​Verify Installation

​Next Steps

Configuration

React Navigation

Push Notifications

API Reference

Prerequisites

Project Setup Patterns

Verify Installation

Next Steps