Documentation Index Fetch the complete documentation index at: https://docs.userboo.st/llms.txt
Use this file to discover all available pages before exploring further.
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)
Get your API key
Sign up at userboo.st
Go to Settings → API Keys
Copy your Client-side API key (starts with ub_live_)
Use the client-side API key for mobile apps, not the server-side key.
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
}
Add to pubspec.yaml dependencies :
userboost : ^1.0.0
Initialize in main.dart import 'package:userboost/userboost.dart' ;
void main () async {
WidgetsFlutterBinding . ensureInitialized ();
await UserBoost . init (
apiKey : 'ub_live_your_client_key_here' ,
debug : kDebugMode,
);
runApp ( MyApp ());
}
For native iOS/Android or other frameworks Use the universal REST API approach: curl -X POST https://api.userboo.st/v1/event \
-H "Authorization: Bearer ub_live_your_client_key_here" \
-H "Content-Type: application/json" \
-d '{
"event": "app_opened",
"user": {
"id": "user_123"
},
"context": {
"platform": "ios",
"app_version": "1.2.0"
}
}'
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'
}
});
import 'dart:io' show Platform;
import 'package:userboost/userboost.dart' ;
// Track app launch
UserBoost . event ( 'app_opened' , {
'user' : {
'id' : 'user_123' ,
'email' : 'john@example.com'
},
'properties' : {
'app_version' : '1.2.0' ,
'platform' : Platform .operatingSystem
}
});
// Track screen navigation
UserBoost . event ( 'screen_viewed' , {
'user' : { 'id' : 'user_123' },
'properties' : {
'screen_name' : 'dashboard' ,
'previous_screen' : 'onboarding'
}
});
// iOS Swift example
func trackEvent ( _ event : String , userId : String , properties : [ String : Any ] = [:]) {
let url = URL ( string : "https://api.userboo.st/v1/event" ) !
var request = URLRequest ( url : url )
request . httpMethod = "POST"
request . setValue ( "Bearer ub_live_your_client_key_here" , forHTTPHeaderField : "Authorization" )
request . setValue ( "application/json" , forHTTPHeaderField : "Content-Type" )
let data : [ String : Any ] = [
"event" : event ,
"user" : [ "id" : userId ],
"properties" : properties
]
request . httpBody = try ? JSONSerialization . data ( withJSONObject : data )
URLSession . shared . dataTask ( with : request ). resume ()
}
// Usage
trackEvent ( "app_opened" , userId : "user_123" , properties : [
"app_version" : "1.2.0" ,
"platform" : "ios"
])
Verify it's working
Go to your UserBoost dashboard
Navigate to Events → Live Stream
Open your mobile app and trigger some events
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
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 ()
}
});
}
};
}
class _MyAppState extends State < MyApp > with WidgetsBindingObserver {
@override
void initState () {
super . initState ();
WidgetsBinding .instance. addObserver ( this );
}
@override
void didChangeAppLifecycleState ( AppLifecycleState state) {
if (state == AppLifecycleState .resumed) {
UserBoost . event ( 'app_opened' , {
'user' : { 'id' : getCurrentUserId ()},
'properties' : {
'session_start' : DateTime . now (). toIso8601String ()
}
});
} else if (state == AppLifecycleState .paused) {
UserBoost . event ( 'app_backgrounded' , {
'user' : { 'id' : getCurrentUserId ()},
'properties' : {
'session_duration' : getSessionDuration ()
}
});
}
}
}
Screen Navigation
// 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 >
);
}
class RouteObserver extends NavigatorObserver {
@override
void didPush ( Route < dynamic > route, Route < dynamic > ? previousRoute) {
if (route.settings.name != null ) {
UserBoost . event ( 'screen_viewed' , {
'user' : { 'id' : getCurrentUserId ()},
'properties' : {
'screen_name' : route.settings.name,
'previous_screen' : previousRoute ? .settings.name,
'timestamp' : DateTime . now (). toIso8601String ()
}
});
}
}
}
// Add to your MaterialApp
MaterialApp (
navigatorObservers : [ RouteObserver ()],
// ... rest of your app
)
User Interactions
// 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'
}
});
};
// Button taps
void handleButtonPress ( String buttonName) {
UserBoost . event ( 'button_tapped' , {
'user' : { 'id' : getCurrentUserId ()},
'properties' : {
'button_name' : buttonName,
'screen' : getCurrentScreen (),
'timestamp' : DateTime . now (). toIso8601String ()
}
});
}
// Form submissions
void handleFormSubmit ( Map < String , dynamic > formData) {
UserBoost . event ( 'form_submitted' , {
'user' : { 'id' : getCurrentUserId ()},
'properties' : {
'form_type' : 'profile_update' ,
'fields_completed' : formData.keys.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:
// 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 ();
// Events are automatically queued offline
UserBoost . event ( 'offline_action' , {
'user' : { 'id' : 'user_123' },
'properties' : { 'action' : 'create_draft' }
});
// Check queue status
int queueLength = await UserBoost . getQueueLength ();
print ( ' $ queueLength events queued' );
// Force flush when back online
UserBoost . flush ();
Push Notifications Integration
Track push notification engagement:
// 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'
}
});
// Track notification received
UserBoost . event ( 'push_notification_received' , {
'user' : { 'id' : getCurrentUserId ()},
'properties' : {
'campaign_id' : notification.campaignId,
'message' : notification.message,
'received_at' : DateTime . now (). toIso8601String ()
}
});
// 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:
// 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__ ,
});
// lib/config.dart
class Config {
static const String apiKey = String . fromEnvironment (
'USERBOOST_API_KEY' ,
defaultValue : 'ub_live_your_dev_key_here'
);
static const bool debug = bool . fromEnvironment ( 'DEBUG' , defaultValue : true );
}
// main.dart
import 'config.dart' ;
await UserBoost . init (
apiKey : Config .apiKey,
debug : Config .debug,
);
Testing & Debugging
Debug Mode
Enable debug mode to see detailed logs:
UserBoost . init ({
apiKey: 'your_key' ,
debug: true , // or __DEV__
});
// Enable verbose logging
UserBoost . setLogLevel ( 'verbose' );
await UserBoost . init (
apiKey : 'your_key' ,
debug : true , // or kDebugMode
);
// Enable verbose logging
UserBoost . setLogLevel ( LogLevel .verbose);
Test Events
Send test events to verify your integration:
// Send test event
UserBoost . event ( 'mobile_integration_test' , {
user: { id: `test_user_ ${ Date . now () } ` },
properties: {
test: true ,
platform: Platform . OS ,
timestamp: new Date (). toISOString ()
}
});
// Send test event
UserBoost . event ( 'mobile_integration_test' , {
'user' : { 'id' : 'test_user_ ${ DateTime . now (). millisecondsSinceEpoch } ' },
'properties' : {
'test' : true ,
'platform' : Platform .operatingSystem,
'timestamp' : DateTime . now (). toIso8601String ()
}
});
Common Issues
Events not appearing in dashboard
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
Events queued but not sending
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.