Skip to main content

​
When to Use Mobile Apps Integration

Perfect for mobile applications:
  • React Native iOS/Android apps
  • Flutter cross-platform apps
  • Native iOS/Android apps (using REST API)
  • Mobile-specific user journey tracking
  • Offline-first mobile experiences
Key benefits:
  • ✅ Native mobile optimization
  • ✅ Platform-specific features and performance
  • ✅ Automatic device and app context
  • ✅ Works offline with intelligent queueing
  • ✅ Seamless cross-platform development

​
Quick Setup (5 minutes)

1

Get your API key

  1. Sign up at userboo.st
  2. Go to Settings → API Keys
  3. Copy your Client-side API key (starts with ub_live_)
Use the client-side API key for mobile apps, not the server-side key.
2

Choose your platform

  • React Native
  • Flutter
  • REST API
Install the React Native SDK
npm install @userboost/react-native
# OR
yarn add @userboost/react-native
Initialize in your App.js
import UserBoost from '@userboost/react-native';

// Initialize once at app startup
UserBoost.init({
  apiKey: 'ub_live_your_client_key_here',
  debug: __DEV__, // Enable in development
});

export default function App() {
  // Your app code
}
3

Track your first event

  • React Native
  • Flutter
  • REST API
import UserBoost from '@userboost/react-native';
import { Platform } from 'react-native';

// Track app launch
UserBoost.event('app_opened', {
  user: {
    id: 'user_123',
    email: 'john@example.com'
  },
  properties: {
    app_version: '1.2.0',
    platform: Platform.OS
  }
});

// Track screen views
UserBoost.event('screen_viewed', {
  user: { id: 'user_123' },
  properties: {
    screen_name: 'dashboard',
    previous_screen: 'onboarding'
  }
});
4

Verify it's working

  1. Go to your UserBoost dashboard
  2. Navigate to Events → Live Stream
  3. Open your mobile app and trigger some events
  4. Events should appear in the dashboard within 30 seconds
Use debug mode during development to see events in your mobile app’s logs.

​
Common Mobile Event Patterns

Track these key mobile-specific events to understand your user journey:

​
App Lifecycle Events

  • React Native
  • Flutter
import { AppState } from 'react-native';
import UserBoost from '@userboost/react-native';

class App extends Component {
  componentDidMount() {
    AppState.addEventListener('change', this.handleAppStateChange);
  }

  handleAppStateChange = (nextAppState) => {
    if (nextAppState === 'active') {
      UserBoost.event('app_opened', {
        user: { id: this.getCurrentUserId() },
        properties: {
          session_start: new Date().toISOString()
        }
      });
    } else if (nextAppState === 'background') {
      UserBoost.event('app_backgrounded', {
        user: { id: this.getCurrentUserId() },
        properties: {
          session_duration: this.getSessionDuration()
        }
      });
    }
  };
}

​
Screen Navigation

  • React Native
  • Flutter
// With React Navigation
import { NavigationContainer } from '@react-navigation/native';

function App() {
  const routeNameRef = useRef();
  const navigationRef = useNavigationContainerRef();

  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={() => {
        routeNameRef.current = navigationRef.getCurrentRoute().name;
      }}
      onStateChange={async () => {
        const previousRouteName = routeNameRef.current;
        const currentRouteName = navigationRef.getCurrentRoute().name;

        if (previousRouteName !== currentRouteName) {
          UserBoost.event('screen_viewed', {
            user: { id: getCurrentUserId() },
            properties: {
              screen_name: currentRouteName,
              previous_screen: previousRouteName,
              timestamp: new Date().toISOString()
            }
          });
        }

        routeNameRef.current = currentRouteName;
      }}
    >
      {/* Your navigation stack */}
    </NavigationContainer>
  );
}

​
User Interactions

  • React Native
  • Flutter
// Button taps
const handleButtonPress = (buttonName) => {
  UserBoost.event('button_tapped', {
    user: { id: getCurrentUserId() },
    properties: {
      button_name: buttonName,
      screen: getCurrentScreen(),
      timestamp: new Date().toISOString()
    }
  });
};

// Form submissions
const handleFormSubmit = (formData) => {
  UserBoost.event('form_submitted', {
    user: { id: getCurrentUserId() },
    properties: {
      form_type: 'profile_update',
      fields_completed: Object.keys(formData).length,
      screen: 'profile_edit'
    }
  });
};

​
Mobile-Specific Features

​
Automatic Context Collection

Mobile SDKs automatically collect device and app context: 
// This context is automatically added to all events:
{
  "context": {
    "platform": "ios",           // or "android"
    "app_version": "1.2.0",
    "device_model": "iPhone 14",
    "os_version": "16.2",
    "screen_size": "390x844",
    "network_type": "wifi",      // or "cellular", "none"
    "timezone": "America/New_York",
    "locale": "en-US"
  }
}

​
Offline Support

Events are automatically queued when offline and sent when connection is restored:
  • React Native
  • Flutter
// Events are automatically queued offline
UserBoost.event('offline_action', {
  user: { id: 'user_123' },
  properties: { action: 'create_draft' }
});

// Check queue status
UserBoost.getQueueLength().then(count => {
  console.log(`${count} events queued`);
});

// Force flush when back online
UserBoost.flush();

​
Push Notifications Integration

Track push notification engagement:
  • React Native
  • Flutter
// Track notification received
UserBoost.event('push_notification_received', {
  user: { id: getCurrentUserId() },
  properties: {
    campaign_id: notification.campaignId,
    message: notification.message,
    received_at: new Date().toISOString()
  }
});

// Track notification tapped
UserBoost.event('push_notification_tapped', {
  user: { id: getCurrentUserId() },
  properties: {
    campaign_id: notification.campaignId,
    action: 'open_app'
  }
});

​
Environment Setup

Configure your API keys for different environments:
  • React Native
  • Flutter
// config/index.js
const config = {
  development: {
    USERBOOST_API_KEY: 'ub_live_your_dev_key_here',
  },
  production: {
    USERBOOST_API_KEY: 'ub_live_your_prod_key_here',
  }
};

export default config[process.env.NODE_ENV || 'development'];

// App.js
import config from './config';
import UserBoost from '@userboost/react-native';

UserBoost.init({
  apiKey: config.USERBOOST_API_KEY,
  debug: __DEV__,
});

​
Testing & Debugging

​
Debug Mode

Enable debug mode to see detailed logs:
  • React Native
  • Flutter
UserBoost.init({
  apiKey: 'your_key',
  debug: true, // or __DEV__
});

// Enable verbose logging
UserBoost.setLogLevel('verbose');

​
Test Events

Send test events to verify your integration:
  • React Native
  • Flutter
// Send test event
UserBoost.event('mobile_integration_test', {
  user: { id: `test_user_${Date.now()}` },
  properties: {
    test: true,
    platform: Platform.OS,
    timestamp: new Date().toISOString()
  }
});

​
Common Issues

Check these common causes:
  • Using server-side API key instead of client-side key
  • Missing required user.id field
  • Network connectivity issues
  • App is in background (some events may be queued)
Enable debug mode to see detailed error messages.
React Native:
# Clear cache and reinstall
npx react-native clean
rm -rf node_modules
npm install

# iOS specific
cd ios && pod install
Flutter:
# Clear cache and reinstall
flutter clean
flutter pub get
  • Check internet connectivity
  • Verify API key is correct
  • Force flush the queue: UserBoost.flush()
  • Check if app has background execution permissions

​
What’s Next?

Track Events

Learn mobile-specific event tracking patterns and best practices.

API Reference

Complete API documentation for REST integration.
Your mobile app is now tracking user events! UserBoost will automatically build user journey funnels and help you identify where users get stuck in your mobile onboarding flow.
⌘I