React Native
Use the Xtremepush SDK to integrate your React Native apps with the Platform
Prerequisites
Before you begin, ensure you have the following:
General Requirements
- React Native 0.71+ (bare workflow, non-Expo)
- Node.js 16.0+
- An Xtremepush account with your Application Key
Android Requirements
- Android Studio with Android SDK installed
- Gradle 7.0+
- Minimum SDK: API 21 (Android 5.0)
- Target SDK: 34
- Firebase project with
google-services.json(Firebase Console setup guide)
iOS Requirements
- Xcode 13.0+
- iOS Deployment Target: 13.0+
- CocoaPods 1.11+
- Apple Developer account with Push Notifications capability enabled
Integration Steps
Step 1: Install the SDK
Add the Xtremepush CLI to your project using npm or Yarn:
npm install xtremepush-react-native-cliyarn add xtremepush-react-native-cliStep 2: Configure the SDK
2.1 Generate Configuration File
Run the following command to create a configuration template:
npx xtremepush-setup generate-configThis creates xtremepush.config.js in your project root.
2.2 Add Your Credentials
Open xtremepush.config.js and add your Xtremepush credentials:
// xtremepush.config.js
module.exports = {
// REQUIRED: Your Xtremepush Application Key
applicationKey: 'YOUR_XTREMEPUSH_APP_KEY',
// REQUIRED for Android: Firebase Cloud Messaging Sender ID
googleSenderId: 'YOUR_FCM_SENDER_ID',
// Enable debug logging during development
enableDebugLogs: true,
// iOS: Your Apple Development Team ID (required for Rich Media)
devTeam: 'YOUR_APPLE_TEAM_ID',
};2.3 Run the Integration
Execute the integration command:
npx xtremepush-setup initThe CLI will automatically:
- Detect your project structure (Android/iOS, Java/Kotlin, Swift/Objective-C)
- Modify native build files and manifests
- Inject SDK initialization code
- Create native bridge modules
Step 3: Android Setup
After running the integration, complete the Android setup:
3.1 Add Firebase Configuration
- Download
google-services.jsonfrom the Firebase Console - Place it in your
android/app/directory:
Verify the file exists
# Verify the file exists
ls android/app/google-services.jsonWithout this file, your Android app will crash on launch with a Firebase initialization error.
3.2 Build the Android App
# Clean the build
cd android && ./gradlew clean && cd ..
# Run the app
npx react-native run-androidCommon Android Build Errors
Gradle sync failed with dependency resolution errors
Solution:
- Check your Internet connection
- Clean and rebuild:
cd android && ./gradlew cleanFirebase initialization error on app launch
Ensure google-services.json is correctly placed in android/app/. Download it from the Firebase Console if missing.
Step 4: iOS Setup
After confirming your Android build, continue with iOS setup:
4.1 Install CocoaPods Dependencies
cd ios && pod install && cd ..4.2 Open in Xcode
open ios/YourApp.xcworkspace4.3 Enable Push Notifications Capability
- In Xcode, select your project in the navigator
- Select your app target
- Go to Signing & Capabilities tab
- Click + Capability
- Add Push Notifications
4.4 Enable Background Modes (Optional)
For background notification handling:
- In Signing & Capabilities, click + Capability
- Add Background Modes
- Check Remote notifications
4.5 Build the iOS App
npx react-native run-iosCommon iOS Build Errors
Pod install failed
Solution:
cd ios
pod repo update
rm -rf Pods Podfile.lock
pod installPush Notifications capability not found
Solution: Ensure you have an Apple Developer account with an active membership and the Push Notifications capability is enabled for your App ID in the Apple Developer Portal.
Step 5: Initialize in Your App
Add the Xtremepush initialization to your React Native code:
// App.js or App.tsx
import React, { useEffect } from 'react';
import { NativeModules, Platform } from 'react-native';
const Xtremepush = NativeModules.Xtremepush;
const App = () => {
useEffect(() => {
// Request notification permissions (required for Android 13+)
Xtremepush.requestNotificationPermissions();
// Check if app was opened from a notification
Xtremepush.getInitialNotification().then(notification => {
if (notification) {
console.log('App opened from notification:', notification);
// Handle deep linking based on notification payload
}
});
}, []);
return (
// Your app content
);
};
export default App;Step 6: Test Your Integration
6.1 Verify SDK Integration
Run the verification command:
npx xtremepush-setup verifyFor detailed output:
npx xtremepush-setup verify --verbose6.2 Check Debug Logs
If you enabled enableDebugLogs: true in your configuration, you'll see SDK logs in:
- Android: Android Studio Logcat (filter by "Xtremepush")
- iOS: Xcode Console
Configuration Reference
All Configuration Options
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
applicationKey | string | Yes | — | Your Xtremepush application key |
googleSenderId | string | Yes | — | Firebase Cloud Messaging sender ID (Android only) |
iosAppKey | string | No | applicationKey | iOS-specific app key if different |
androidAppKey | string | No | applicationKey | Android-specific app key if different |
enableDebugLogs | boolean | No | false | Enable SDK debug logging |
enableLocationServices | boolean | No | true | Enable location permissions |
enableGeo | boolean | No | false | Enable geofencing |
enableBeacons | boolean | No | false | Enable iBeacon support |
enableRichMedia | boolean | No | false | Enable rich notifications (iOS Service Extension) |
serverUrl | string | No | — | Custom Xtremepush server URL |
useUsServer | boolean | No | false | Use US region server |
enablePinning | boolean | No | false | Enable SSL certificate pinning |
certificatePath | string | No | — | Path to SSL certificate (.cer) |
devTeam | string | No | — | Apple Team ID (required for Service Extension) |
apsEnvironment | string | No | development | APNs environment: development or production |
Example: Full Configuration
// xtremepush.config.js
module.exports = {
// Required
applicationKey: 'YOUR_XTREMEPUSH_APP_KEY',
googleSenderId: 'YOUR_FCM_SENDER_ID',
// Platform-specific keys (optional)
iosAppKey: 'YOUR_IOS_APP_KEY',
androidAppKey: 'YOUR_ANDROID_APP_KEY',
// Features
enableDebugLogs: false, // Disable in production
enableLocationServices: true,
enableGeo: true, // Geofencing
enableBeacons: false, // iBeacon support
enableRichMedia: true, // Rich push (iOS)
// Server
useUsServer: false,
serverUrl: '',
// Security
enablePinning: false,
certificatePath: './certs/xtremepush.cer',
// iOS
devTeam: 'ABCD1234EF',
apsEnvironment: 'production',
};Alternative: Configuration in package.json
{
"name": "your-app",
"xtremepush": {
"applicationKey": "YOUR_XTREMEPUSH_APP_KEY",
"googleSenderId": "YOUR_FCM_SENDER_ID",
"enableDebugLogs": true
}
}JavaScript API Reference
Importing the Module
import { NativeModules } from 'react-native';
const Xtremepush = NativeModules.Xtremepush;User Identification
Identify users across sessions and devices:
// Set user by email or custom ID
Xtremepush.setUser('[email protected]');
// Set external ID for cross-platform identification
Xtremepush.setExternalId('your_user_id_123');Best Practice: Call
setUser()after user login and clear it on logout.
Event Tracking
Track user actions and behaviors:
// Track a custom event
Xtremepush.hitEvent('purchase_completed');
// Add a tag to user profile
Xtremepush.hitTag('premium_user');
// Add a tag with a value
Xtremepush.hitTagWithValue('plan_type', 'enterprise');
Xtremepush.hitTagWithValue('signup_date', '2025-01-15');Push Notifications
// Request notification permissions (required for Android 13+)
Xtremepush.requestNotificationPermissions();
// Get notification that opened the app
Xtremepush.getInitialNotification().then(notification => {
if (notification) {
console.log('Notification payload:', notification);
// Navigate based on notification data
}
});Message Center (Inbox)
// Open the Xtremepush message inbox
Xtremepush.openInbox();Complete Example
import React, { useEffect, useState } from 'react';
import { View, Button, Text, NativeModules } from 'react-native';
const Xtremepush = NativeModules.Xtremepush;
export default function App() {
const [userId, setUserId] = useState(null);
useEffect(() => {
// Request permissions on app start
Xtremepush.requestNotificationPermissions();
// Handle notification that opened the app
Xtremepush.getInitialNotification().then(notification => {
if (notification) {
console.log('Opened via notification:', notification);
}
});
}, []);
const handleLogin = (email) => {
// After successful login
Xtremepush.setUser(email);
Xtremepush.hitEvent('user_login');
setUserId(email);
};
const handlePurchase = (productId, amount) => {
Xtremepush.hitEvent('purchase');
Xtremepush.hitTagWithValue('last_purchase_amount', amount.toString());
Xtremepush.hitTag('has_purchased');
};
const handleSubscribe = (planType) => {
Xtremepush.hitTag('subscriber');
Xtremepush.hitTagWithValue('subscription_plan', planType);
};
return (
<View style={{ flex: 1, justifyContent: 'center', padding: 20 }}>
<Button
title="Login"
onPress={() => handleLogin('[email protected]')}
/>
<Button
title="Track Purchase"
onPress={() => handlePurchase('prod_123', 99.99)}
/>
<Button
title="Subscribe to Pro"
onPress={() => handleSubscribe('pro')}
/>
<Button
title="Open Inbox"
onPress={() => Xtremepush.openInbox()}
/>
</View>
);
}Advanced Features
Rich Media Notifications (iOS)
Display images, videos, and interactive buttons in notifications:
-
Enable in configuration:
module.exports = { enableRichMedia: true, devTeam: 'YOUR_APPLE_TEAM_ID', }; -
Re-run integration:
npx xtremepush-setup ios -
In Xcode, verify the XtremePushNotificationServiceExtension target exists
-
Add Push Notifications capability to the extension target
Rich media requires the
devTeamto be set for the Service Extension to be created.
Location Services & Geofencing
Enable location-based targeting:
module.exports = {
enableLocationServices: true, // Basic location
enableGeo: true, // Geofencing
enableBeacons: true, // iBeacon proximity
};Permissions added automatically:
- Android:
ACCESS_FINE_LOCATION,ACCESS_COARSE_LOCATION,ACCESS_BACKGROUND_LOCATION - iOS: Location usage descriptions in Info.plist
SSL Certificate Pinning
For enhanced security in enterprise environments:
module.exports = {
enablePinning: true,
certificatePath: './certs/xtremepush.cer',
};Contact Xtremepush support to obtain the correct certificate file.
CLI Command Reference
| Command | Description |
|---|---|
npx xtremepush-setup init | Run full integration (Android + iOS) |
npx xtremepush-setup android | Android integration only |
npx xtremepush-setup ios | iOS integration only |
npx xtremepush-setup verify | Check integration status |
npx xtremepush-setup generate-config | Generate configuration template |
Command Options
| Option | Description |
|---|---|
-c, --config <path> | Custom config file path |
--skip-android | Skip Android integration |
--skip-ios | Skip iOS integration |
--dry-run | Preview changes without applying |
-y, --yes | Skip confirmation prompts |
Examples
# Preview what will change
npx xtremepush-setup init --dry-run
# Use custom config file
npx xtremepush-setup init --config ./config/prod.config.js
# Android only, no prompts
npx xtremepush-setup android --yes
# iOS only with verbose verification
npx xtremepush-setup ios && npx xtremepush-setup verify --verboseTroubleshooting
Notifications Not Received
- Check device registration: Enable
enableDebugLogs: trueand look for device token registration - Verify push credentials: Ensure certificates/keys are configured in Xtremepush dashboard
- Test from dashboard: Send a test notification from Xtremepush → Campaigns
- Check device settings: Ensure notifications are enabled for your app
Integration Verification Failed
Run detailed verification:
npx xtremepush-setup verify --verboseManual checks:
# Android - Check SDK initialization
grep -r "XtremePush" android/app/src/main/java/
# iOS - Check SDK initialization
grep -r "XtremePush" ios/*/AppDelegate.*Debug Mode
Enable verbose CLI output:
DEBUG=1 npx xtremepush-setup initGetting Support
If issues persist:
- Run:
npx xtremepush-setup verify --verbose - Enable:
enableDebugLogs: true - Contact Xtremepush support with:
- Verification output
- Device/simulator logs
- Configuration (redact sensitive keys)
What Gets Modified
Android Files
| File | Modifications |
|---|---|
android/settings.gradle | Xtremepush Maven repository |
android/build.gradle | Google Services classpath |
android/app/build.gradle | SDK dependencies, plugins |
AndroidManifest.xml | Permissions (location if enabled) |
MainActivity.java/kt | Notification payload capture |
MainApplication.java/kt | SDK initialization |
iOS Files
| File | Modifications |
|---|---|
ios/Podfile | Xtremepush pods |
Info.plist | Background modes, usage descriptions |
*.entitlements | aps-environment, app groups |
AppDelegate.swift/m | SDK initialization |
SDK Versions
| Component | Version |
|---|---|
| Xtremepush Android SDK | 9.6.0 |
| Xtremepush iOS SDK | Latest (CocoaPods) |
| Firebase Messaging | 25.0.0 |
| Play Services Location | 21.3.0 |
Language Support
The CLI automatically detects and generates code for:
| Platform | Supported Languages |
|---|---|
| Android | Java, Kotlin |
| iOS | Swift, Objective-C |
Updated 16 days ago