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

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