Xtremepush React Native SDK Setup

Integrate push notifications, in-app messaging, location services, and user analytics into your React Native application.

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

Step 1: Install the SDK

Add the Xtremepush CLI to your project using npm or Yarn:

# Using npm
npm install xtremepush-react-native-cli

# Using Yarn
yarn add xtremepush-react-native-cli

Or run directly without installing:

npx xtremepush-setup <command>

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',
};

Where to find your credentials:

• Application Key: Xtremepush Dashboard → Settings → App Keys
• FCM Sender ID: Firebase Console → Project Settings → Cloud Messaging → Sender ID
• Apple Team ID: Apple Developer Portal → Membership → 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

Note: The integration is idempotent—you can safely run it multiple times without duplicating code.

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
ls android/app/google-services.json

Important: Without 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-android

Common Android Build Errors

Solution:

1. Check your internet connection
2. Verify Maven repository access:

   curl -I https://maven.xtremepush.com/artifactory/xtremepush-android-sdk

3. Clean and rebuild:

   cd android && ./gradlew clean

Solution: 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 works, continue with iOS setup:

4.1 Install CocoaPods Dependencies

cd ios && pod install && cd ..

4.2 Open in Xcode

open ios/YourApp.xcworkspace

Important: Always open the .xcworkspace file, not the .xcodeproj.

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

Solution:

cd ios
pod repo update
rm -rf Pods Podfile.lock
pod install

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 Send a Test Notification

1. Log in to your Xtremepush Dashboard
2. Navigate to Create Campaign → Push Notification
3. Select your app and create a test message
4. Send to a test device

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

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

Note: 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',
};

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

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

License

MIT License © 2025 Xtremepush