Xtremepush React Native SDK Setup

Guide to integrating Xtremepush SDK 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


---

## Step 2: Configure the SDK

### 2.1 Generate Configuration File

Run the following command to create a configuration template:

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

Download google-services.json from the Firebase Console
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

Gradle sync failed with dependency resolution errors

Solution:

Check your internet connection

Verify Maven repository access:

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

Clean and rebuild:
```
cd android && ./gradlew clean
```

Firebase initialization error on app launch

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

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

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('user@example.com');

// 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('user@example.com')}
      />
      <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

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

Check device registration: Enable enableDebugLogs: true and 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 --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:

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

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
node_modules		node_modules
src		src
templates		templates
.DS_Store		.DS_Store
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

xtremepush/react-native-cli

Folders and files

Latest commit

History

Repository files navigation