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-cli

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:

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:

// 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 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

2. Place it in your android/app/ directory:

Verify the file exists

# Verify the file exists
ls android/app/google-services.json

3.2 Build the Android App

# 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:

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

cd ios && pod install && cd ..

4.2 Open in Xcode

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

npx react-native run-ios

Common iOS Build Errors

Pod install failed

Solution:

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:

// 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 verify

For detailed output:

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

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');

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:

1. Enable in configuration:

   module.exports = {
     enableRichMedia: true,
     devTeam: 'YOUR_APPLE_TEAM_ID',
   };

2. Re-run integration:

   npx xtremepush-setup ios

3. In Xcode, verify the XtremePushNotificationServiceExtension target exists

4. Add Push Notifications capability to the extension target

   Rich media requires the devTeam to 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',
};

CLI Command Reference

Command Options

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 --verbose

Troubleshooting

Notifications Not Received

1. Check device registration: Enable enableDebugLogs: true and look for device token registration

2. Verify push credentials: Ensure certificates/keys are configured in Xtremepush dashboard

3. Test from dashboard: Send a test notification from Xtremepush → Campaigns

4. Check device settings: Ensure notifications are enabled for your app

Integration Verification Failed

Run detailed verification:

npx xtremepush-setup verify --verbose

Manual 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 init

Getting Support

If issues persist:

1. Run: npx xtremepush-setup verify --verbose

2. Enable: enableDebugLogs: true

3. Contact Xtremepush support with:

   • Verification output

   • Device/simulator logs

   • Configuration (redact sensitive keys)

What Gets Modified

Android Files

iOS Files

SDK Versions

Language Support

The CLI automatically detects and generates code for: