react-native-xtremepush

Xtremepush SDK for bare React Native — an autolinkable native module for iOS and Android, plus a setup CLI for the host configuration that autolinking cannot do on its own.

Expo? This package is for bare React Native apps. Expo apps are served by the separate xtremepush-expo-plugin config plugin — do not use this package with Expo prebuild.

Prerequisites

• React Native 0.71+ (bare workflow, non-Expo). New architecture is supported via the RN interop layer.
• Node.js 16.0+
• An Xtremepush account with your Application Key
• Android: Android Studio; minSdkVersion 21+; a Firebase project with google-services.json
• iOS: Xcode 14+; iOS deployment target 15.0+; CocoaPods 1.11+; an Apple Developer account with the Push Notifications capability

1. Install

npm install react-native-xtremepush
# or
yarn add react-native-xtremepush

iOS

cd ios && pod install && cd ..

use_native_modules! (already in every RN Podfile) discovers the library's podspec and installs the pod and the Xtremepush-iOS-SDK dependency transitively — no Podfile edit.

Android

Autolinking includes the library's Gradle module and registers the bridge package automatically. The XtremePush SDK dependencies come from the library's own android/build.gradle, so you do not add them to your app.

One thing autolinking cannot do is add the XtremePush Maven repository to your host settings.gradle. The CLI does this for you — see step 2.

2. Run the setup CLI

Generate a config template, fill in your credentials, then run the integration:

npx xtremepush-setup generate-config   # writes xtremepush.config.js
npx xtremepush-setup init              # applies host changes (idempotent)

// xtremepush.config.js
module.exports = {
  // Required
  applicationKey: 'YOUR_XTREMEPUSH_APP_KEY',
  googleSenderId: 'YOUR_FCM_SENDER_ID',   // Android (FCM)

  // Optional
  enableLocationServices: true,           // add location permissions
  enableRichMedia: false,                 // iOS Notification Service Extension
  devTeam: 'YOUR_APPLE_TEAM_ID',          // required if enableRichMedia
};

The CLI applies only the non-autolinkable host changes:

Android — Maven repo in settings.gradle; google-services classpath in project build.gradle; google-services plugin in app/build.gradle; opt-in location permissions in AndroidManifest.xml; cold-start notification capture in MainActivity (feeds getInitialNotification()).

iOS — Info.plist background modes / usage strings; entitlements (aps-environment, App Group); push-token forwarding delegate methods in AppDelegate; and, if enableRichMedia is set, the rich-media Notification Service Extension target.

The CLI is idempotent — safe to run more than once.

Android: add google-services.json

Download it from the Firebase Console and place it at android/app/google-services.json, then rebuild:

cd android && ./gradlew clean && cd ..
npx react-native run-android

iOS: enable capabilities

In Xcode (open the .xcworkspace), select your app target → Signing & Capabilities → add Push Notifications (and Background Modes → Remote notifications if you want background handling), then build:

npx react-native run-ios

3. Initialize at runtime (required)

Call initialize() as early as possible in your app entry, before any other Xtremepush call. This is what registers the device and starts event delivery.

import * as Xtremepush from 'react-native-xtremepush';

// App entry (e.g. index.js), before rendering
Xtremepush.initialize({
  appKey: 'YOUR_XTREMEPUSH_APP_KEY',
  senderId: 'YOUR_FCM_SENDER_ID', // Android
  // region: 'us',                // only if your project is on the US data centre
});

Data region. EU is the default. Set region: 'us' (or useUsServer: true, or an explicit serverUrl) only if your Xtremepush project is on the US data centre. Sending to the wrong region is a common reason events never appear on the dashboard.

Calls made before initialize() resolves are no-ops (they will not crash), so guard your first hitEvent/setUser behind app startup.

initialize(config) options

| Option | Type | Platform | Default | Description | |--------|------|----------|---------|-------------| | appKey | string | both | — | Required. Xtremepush application key | | senderId | string | Android | — | FCM sender id | | region | 'eu' \| 'us' | both | 'eu' | Data-centre region | | useUsServer | boolean | both | false | Alternative to region: 'us' | | serverUrl | string | both | — | Explicit host; overrides region | | inAppMessaging | boolean | both | true | Enable in-app messaging | | debugLogs | boolean | both | false | Verbose SDK logging | | startSession | boolean | Android | true | Session-start tracking | | enableDeliveryReceipts | boolean | both | false | Report push delivery to the dashboard. On iOS requires iosAppGroup and the Notification Service Extension | | deliveryReceiptsEndpoint | string | iOS | — | Custom reporting endpoint for delivery receipts | | enableEncryptedMessages | boolean | Android | false | Enable encrypted push messages (SDK >= 8.1.0) | | enableEncryptedPush | boolean | iOS | false | Enable encrypted push notifications. Requires iosAppGroup and the Notification Service Extension | | iosAppGroup | string | iOS | — | Shared App Group id for the Notification Service Extension. Required with enableDeliveryReceipts/enableEncryptedPush | | loyaltyEndpoint | string | both | — | Enables the Loyalty Widget integration | | serverExpectedPublicKey | string | Android | — | SSL pinning: the server's expected public key | | enablePinning | boolean | iOS | false | Enable SSL certificate pinning. Requires certificateFileName | | certificateFileName | string | iOS | — | Filename of the certificate bundled by the xtremepush-setup CLI (from certificatePath) | | sandbox | boolean | iOS | — | Use the APNs sandbox environment | | requestPermissions | boolean | iOS | true | Request notification permission at init |

Controlling the notification permission prompt

The permission prompt is triggered differently on each platform — this is intentional:

• iOS shows the OS permission prompt automatically during initialize(), because requestPermissions defaults to true. To defer it — e.g. so you can show your own "why we send notifications" pre-permission screen first — pass requestPermissions: false.
• Android never prompts during initialize(). The runtime POST_NOTIFICATIONS prompt (Android 13+) is only shown when you explicitly call requestNotificationPermissions(). There is no requestPermissions init flag on Android because init never prompts.

To defer the prompt and control it yourself on both platforms:

// 1. At startup — disables the automatic iOS prompt; Android is already deferred
await Xtremepush.initialize({ appKey: 'YOUR_APP_KEY', requestPermissions: false });

// 2. Later, when the user opts in (e.g. taps "Enable notifications")
Xtremepush.requestNotificationPermissions();

requestNotificationPermissions() works on both platforms and is safe to call at any time after initialize() resolves. On iOS, if permission was already granted (or the prompt already shown at init) it is a no-op; on Android it shows the system prompt on the current activity.

Delivery receipts & encrypted push (iOS Notification Service Extension)

On iOS, delivery receipts and encrypted push are configured inside the Notification Service Extension's own process, not just the main app — the NSE and main app exchange data via a shared App Group. Run xtremepush-setup init with enableDeliveryReceipts and/or enableEncryptedPush set in xtremepush.config.js — this creates the NSE (same as enableRichMedia), wires the App Group entitlement, and generates the NSE's init() with the matching XPush calls. Then pass the same flags to initialize():

await Xtremepush.initialize({
  appKey,
  enableDeliveryReceipts: true,
  deliveryReceiptsEndpoint: 'https://your-endpoint.example.com', // optional
  enableEncryptedPush: true,
  iosAppGroup: 'group.com.yourapp.xtremepush', // must match xtremepush.config.js
});

On Android, enableDeliveryReceipts and enableEncryptedMessages (SDK >= 8.1.0) work from initialize() alone — no CLI step or App Group needed.

Loyalty Widget endpoint

Set loyaltyEndpoint on initialize() (both platforms) to enable the Loyalty Widget integration. See Loyalty Widget below for the rest of the API (setLoyaltyToken, openLoyalty, getLoyaltyUrl, onLoyaltyTokenRefresh) — none of it functions until loyaltyEndpoint is set.

SSL pinning

• Android — pass serverExpectedPublicKey (the server's expected public key) directly to initialize(). No CLI step required.
• iOS — set certificatePath in xtremepush.config.js and run xtremepush-setup init to copy the certificate into the app bundle. Then pass enablePinning: true and certificateFileName (the certificate's filename, e.g. 'xtremepush.cer') to initialize().

JavaScript API

import * as Xtremepush from 'react-native-xtremepush';

Lifecycle & identity

await Xtremepush.initialize({ appKey, senderId });
Xtremepush.setUser('[email protected]');
Xtremepush.setExternalId('your_user_id_123');
Xtremepush.setLanguage('en');
Xtremepush.requestNotificationPermissions();

Events, tags & impressions

Xtremepush.hitEvent('purchase_completed');
Xtremepush.hitEventWithValue('level_up', '10');
Xtremepush.hitEventWithValues('checkout', { amount: 99.99, currency: 'EUR' });
Xtremepush.hitImpression('home_banner');
Xtremepush.hitTag('premium_user');
Xtremepush.hitTagWithValue('plan_type', 'enterprise');

Notifications & inbox

const opened = await Xtremepush.getInitialNotification(); // notification that launched the app
Xtremepush.openInbox();

const messages = await Xtremepush.getInboxMessages();
const badge = await Xtremepush.getInboxBadge();
await Xtremepush.reportMessageOpened(messageId);
await Xtremepush.deleteInboxMessage(messageId);

Subscription preferences

await Xtremepush.updatePushSubscriptionPreferences({ marketing: true });
await Xtremepush.updateEmailSubscriptionPreferences({ newsletters: false });
await Xtremepush.updateSmsSubscriptionPreferences({ alerts: true });

Event listeners

Names are fixed, so subscribe with just a handler; call .remove() to unsubscribe.

const sub = Xtremepush.onMessageResponse(({ message, response }) => { /* … */ });
Xtremepush.onDeeplinkReceived(({ deeplink }) => { /* navigate */ });
Xtremepush.onInboxBadgeUpdate(({ badge }) => { /* update UI */ });
Xtremepush.onInboxInvalidated(() => { /* refetch inbox */ });

// later
sub.remove();

Loyalty

Xtremepush.setLoyaltyToken(token);
Xtremepush.openLoyalty('/rewards');
const url = await Xtremepush.getLoyaltyUrl('/rewards');
Xtremepush.onLoyaltyTokenRefresh(async () => await fetchFreshToken());

See src/index.d.ts for the full typed surface.

CLI reference

| Command | Description | |---------|-------------| | npx xtremepush-setup init | Apply host configuration (Android + iOS) | | npx xtremepush-setup android | Android host configuration only | | npx xtremepush-setup ios | iOS host configuration only | | npx xtremepush-setup verify | Check the host configuration | | npx xtremepush-setup generate-config | Write a config template |

| Option | Description | |--------|-------------| | -c, --config <path> | Custom config file path | | --skip-android / --skip-ios | Skip a platform | | --dry-run | Preview changes without applying | | -y, --yes | Skip confirmation prompts |

Troubleshooting

Events don't appear on the dashboard. The most common causes:

1. initialize() was never called, or was called after the first event — call it at app entry and await it (or guard early calls).
2. Wrong data region — if your dashboard is US, pass region: 'us'.
3. Device not registered — enable debugLogs: true and confirm a device token / XtremePush initialized line in logcat (Android) or the Xcode console (iOS).
4. Android: missing google-services.json in android/app/.

NativeModules.Xtremepush is null. Rebuild after installing (autolinking runs at build time): cd ios && pod install for iOS; ./gradlew clean then re-run for Android. Confirm the package installed under node_modules/react-native-xtremepush.

Enable verbose CLI output with DEBUG=1 npx xtremepush-setup init.

SDK versions

| Component | Version | |-----------|---------| | Xtremepush Android SDK | 9.8.2 (bundled via the library's android/build.gradle) | | Xtremepush iOS SDK | 6.1.6 (pinned via the podspec Xtremepush-iOS-SDK dependency) |

License

MIT © Xtremepush