--- title: "React Native" slug: "react-native" updated: 2026-06-09T22:38:47Z published: 2026-06-09T22:38:47Z canonical: "docs.xtremepush.com/react-native" stale: true --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.xtremepush.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://console.firebase.google.com/)) ### 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** ```plaintext npm install xtremepush-react-native-cli ``` **yarn** ```plaintext yarn add xtremepush-react-native-cli ``` ### Step 2: Configure the SDK #### 2.1 Generate Configuration File Run the following command to create a configuration template: ```Terminal npx xtremepush-setup generate-config ``` This creates `xtremepush.config.js` in your project root. #### 2.2 Add Your Credentials Open `xtremepush.config.js` and add your Xtremepush credentials: ```javascript // 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: ```Terminal npx xtremepush-setup init ``` The 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 1. Download `google-services.json` from the [Firebase Console](https://console.firebase.google.com/) 2. Place it in your `android/app/` directory: Verify the file exists ```Terminal # Verify the file exists ls android/app/google-services.json ``` > [!WARNING] > Without this file, your Android app will crash on launch with a Firebase initialization error. #### 3.2 Build the Android App ```Terminal # Clean the build cd android && ./gradlew clean && cd .. # Run the app npx react-native run-android ``` ### Common Android Build Errors #### Gradle sync failed with dependency resolution errors **Solution**: 1. Check your Internet connection 2. Clean and rebuild: ```Terminal cd android && ./gradlew clean ``` #### Firebase 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 ```Terminal cd ios && pod install && cd .. ``` #### 4.2 Open in Xcode ```Terminal open ios/YourApp.xcworkspace ``` #### 4.3 Enable Push Notifications Capability 1. In Xcode, select your **project** in the navigator 2. Select your **app target** 3. Go to **Signing & Capabilities** tab 4. Click **+ Capability** 5. Add **Push Notifications** #### 4.4 Enable Background Modes (Optional) For background notification handling: 1. In **Signing & Capabilities**, click **+ Capability** 2. Add **Background Modes** 3. Check **Remote notifications** #### 4.5 Build the iOS App ```Terminal npx react-native run-ios ``` ### Common iOS Build Errors #### Pod install failed **Solution**: ```Terminal cd ios  pod repo update  rm -rf Pods Podfile.lock  pod install ``` #### Push 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: ```javascript // 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: ```Terminal npx xtremepush-setup verify ``` For detailed output: ```Terminal npx xtremepush-setup verify --verbose ``` #### 6.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 ```javascript // 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 ```json {  "name": "your-app",  "xtremepush": {    "applicationKey": "YOUR_XTREMEPUSH_APP_KEY",    "googleSenderId": "YOUR_FCM_SENDER_ID",    "enableDebugLogs": true  } } ``` ## JavaScript API Reference ### Importing the Module ```javascript import { NativeModules } from 'react-native'; const Xtremepush = NativeModules.Xtremepush; ``` ### User Identification Identify users across sessions and devices: ```javascript // Set user by email or custom ID Xtremepush.setUser('[email protected]'); // Set external ID for cross-platform identification Xtremepush.setExternalId('your_user_id_123'); ``` > [!TIP] > **Best Practice:** Call `setUser()` after user login and clear it on logout. ### Event Tracking Track user actions and behaviors: ```javascript // 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 ```javascript // 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) ```javascript // Open the Xtremepush message inbox Xtremepush.openInbox(); ``` ### Complete Example ```javascript 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 (