Expo Setup

iOS FCM limitation: the Expo Notifications plugin still automatically registers a raw APNs token on iOS. The current AlgorithmX sender requires an FCM token on both platforms. This plugin path supports SDK startup and API-based in-app campaigns, but does not complete iOS FCM push setup. Use the React Native Firebase/native Firebase path for iOS push and preserve native changes through your app's configuration.

Use this path with Expo SDK 55 and Expo Notifications. It uses the same AlgorithmX React Native SDK and JavaScript API. The optional integration configures native startup and push callbacks during prebuild, so you do not edit MainApplication or AppDelegate manually.

Use React Native SDK 1.1.1 for the current package. The Expo plugin's startup integration was verified with Expo 55; other Expo versions need validation before support is extended. Use a native development or release build. Expo Go is unsupported.

If your Expo app already uses React Native Firebase messaging or a custom Android push service, follow the matching React Native path and preserve its native configuration using your existing plugin. The plugin on this page requires Expo Notifications to own that route.

What to expect

You will make two kinds of changes: configuration in app.json (or your existing Expo app config), and JavaScript for customers, events, permissions, and navigation. The plugin generates the native startup and push integration when you prebuild. You do not need to write AlgorithmX calls in MainApplication or AppDelegate for this route.

Start by getting one platform working. For an iPhone in-app test, prepare your iOS bundle ID and Apple signing. Your AlgorithmX contact supplies the API base URL and partner ID; replace the example values below with those for your environment. API-based in-app campaigns work before push is configured. Android push additionally needs its Firebase configuration and the shared service-account connection. iOS push needs the separate FCM path described above.

1. Install

npx expo install @algorithmxcloud/react-native-sdk@^1.1.1
npx expo install expo-notifications

Run these commands from your Expo app's folder. You can use your existing project; creating a new demo app is optional. For a development client, also install expo-dev-client if your project uses one.

Check before continuing: both packages appear in package.json. You have installed the code, but the phone will only have the native SDK after the build in step 3.

2. Configure once

Add the AlgorithmX plugin after expo-notifications in app.json:

{
  "expo": {
    "name": "Your App",
    "slug": "your-app",
    "ios": { "bundleIdentifier": "com.example.shop" },
    "android": {
      "package": "com.example.shop",
      "googleServicesFile": "./google-services.json"
    },
    "plugins": [
      ["expo-notifications", { "enableBackgroundRemoteNotifications": true }],
      ["@algorithmxcloud/react-native-sdk", {
        "apiBaseUrl": "https://api.example.com",
        "partnerId": "your-partner-id"
      }]
    ]
  }
}

Keep your app's existing name, bundle ID, and package name when merging this example. The plugin order matters: Expo Notifications is configured first, then AlgorithmX adds its integration. The example includes Android push configuration; omit googleServicesFile while testing API-based in-app campaigns without Firebase.

For Android push, the file must come from the connected Firebase project. Upload its service-account JSON to AlgorithmX. EAS signing credentials alone do not configure AlgorithmX's sender; Apple APNs credentials for the iOS FCM route belong in Firebase.

The plugin writes URL and partner ID to native configuration, adds the underlying iOS SDK's Git pod dependency, enables iOS push/background settings, and installs one Android service that handles AlgorithmX messages and forwards other messages to Expo Notifications. Expo lifecycle hooks initialize the SDK before JavaScript and register platform push tokens when their native setup is available. Android FCM registration requires a configured default Firebase app.

Check before building: the API URL and partner ID belong to the same AlgorithmX environment. For the push test, also verify that the Firebase file belongs to your Android app and that AlgorithmX has the sending credentials. App signing lets you install the app; sending credentials let AlgorithmX reach it with a push.

3. Build the native app

Prebuild turns your Expo configuration into native Android/iOS projects. Build the platform you want to test; you can add the other one afterward.

For a connected iPhone:

npx expo prebuild --platform ios
npx expo run:ios --device

Choose your connected phone when prompted and use your app's normal Apple signing setup. For Android:

npx expo prebuild --platform android
npx expo run:android

You can also use your existing EAS development/release build workflow. Configuration changes require a new native build; an over-the-air JavaScript update cannot change native settings.

For projects using continuous native generation, the plugin reapplies settings after a clean prebuild. A clean prebuild regenerates native directories, so preserve any app-owned manual native work before using that option.

Check before continuing: your newly built app opens on the phone. This confirms installation and native compilation. It does not yet prove that your API URL is reachable or that a push can be delivered.

4. Use the shared JavaScript integration

Add listeners, customers, and events, then connect at startup:

import AlgorithmX from '@algorithmxcloud/react-native-sdk';

async function startAlgorithmX() {
  await AlgorithmX.init();
  AlgorithmX.setLoggingEnabled(__DEV__);
}

startAlgorithmX().catch((error) => console.warn('AlgorithmX startup failed', error));

The native SDK has already started with the plugin configuration. init() connects JavaScript to it. Continue with the linked shared JavaScript guide to register all your listeners together, identify your current customer, and send your first event. These are app-level startup tasks, so keep them outside individual screens.

No URL or partner ID is repeated in JavaScript. Do not also use the /firebase adapter or manually forward AlgorithmX native messages.

Permissions and other notifications

Choose a moment when the customer understands why notifications would help, such as an Enable notifications button in your settings. Registering a push token and asking to show visible alerts are separate things: the native integration handles the token; your app chooses when to ask for permission.

Keep your Expo Notifications permission flow. AlgorithmX does not request visible-notification permission. Use Expo's permission APIs at the time your app chooses; on Android 13 and later, follow Expo's channel/permission ordering.

Other notifications retain Expo's handling. Use AlgorithmX's specific JavaScript action/link callbacks for AlgorithmX navigation. Do not navigate for the same campaign from both an Expo notification callback and an AlgorithmX callback. Background tasks should also avoid forwarding AlgorithmX payloads again; Expo's iOS background subscriber may observe the same APNs delivery.

The plugin registers Android FCM tokens natively. Its automatic iOS registration still sends an APNs token, which cannot be used by the FCM-only sender. An ExponentPushToken[...] from getExpoPushTokenAsync() is also not accepted. Follow the iOS FCM path, avoiding duplicate registration from the plugin's legacy token path.

The iOS integration composes with Expo's notification-center delegate. An additional library that replaces that delegate after startup needs its own integration assessment. The plugin also keeps background push callbacks available. API-based in-app views only require SDK startup; they do not require background push delivery or an extension. On Android in SDK 1.1.0, Firebase token registration only runs when a default Firebase app exists, so in-app startup also works before push is configured.

Try your first campaign

Use one test customer on a real phone. First identify that customer and send an event; confirm both appear in AlgorithmX. Publish an eligible in-app campaign, then leave the app and return. Confirm the automatic API fetch, rendered campaign, impression and close results.

Production backend support is pending: the .NET delivery route is tracked in AlgorithmX issue #207. SDK 1.1.0 with Expo 55 passed physical-device tests on a Samsung Galaxy A51 and iPhone 13 using in-app-test-backend fixtures. Checks covered automatic customer/language queries, rendered campaigns, real Close buttons, custom events, account switching, logout and the configured demo account on restart. Android startup also passed without Firebase configured. Production campaign processing and push delivery require separate verification.

For Android, enable visible notifications and complete the dashboard FCM test, then send an AlgorithmX campaign to check actions. For iOS, first complete the separate Firebase integration; the plugin's APNs token is insufficient. A token registration, a successful send, and a campaign impression are different checkpoints.

For a backend running on your computer, use an address the phone can reach on the same network. localhost on the phone points to the phone itself. Allow the app's Local Network access on iOS, and configure development HTTP access if your test URL uses HTTP. Prefer HTTPS for the normal integration. Once connectivity is restored, repeat your test action; an event that failed offline is not replayed automatically.

Optional rich notifications on iOS

You can finish the basic integration and test your first campaign before adding rich notifications. Add this section when your campaigns need images, action buttons, or extension-based delivery reports.

For AlgorithmX images and action buttons in iOS notifications, create or reuse a Notification Service Extension. The same requirement applies to Expo apps. Our plugin does not create, embed, or sign this separate target. Basic notifications, taps, background push callbacks, and API-based in-app campaigns work without it.

Click to enlarge

Close image ×

The extension is a separate iOS target. This native Swift Package Manager example links the SDK; Expo apps add AlgorithmX's standalone helper file to that target.

1. Generate the iOS project with npx expo prebuild, then open ios/YourApp.xcworkspace in Xcode.
2. Follow the React Native extension setup: create/reuse and sign the extension, download AlgorithmX's 1.1.0 helper, add it to the extension target only, and call it from NotificationService.swift. The helper is also in the versioned iOS SDK source.
3. For delivery/impression reports, add appGroup: "group.com.example.shop" to the AlgorithmX plugin options above. The plugin shares SDK configuration and adds the App Group entitlement to the main app. Enable/provision the same group for the extension and pass it to processNotification. Images and buttons alone do not need an App Group.
4. Preserve the extension target, helper file, and entitlements through your project's existing config plugin when using clean prebuild or generated native projects for EAS. Manual Xcode changes alone are lost by npx expo prebuild --clean; our plugin does not regenerate this extension.

Rebuild the native app, verify extension signing in your EAS/Xcode build, and test image/button delivery on an iPhone. Refresh the helper when upgrading the SDK.

Next: run the device release checklist, including clean prebuild, token refresh, unrelated notifications, and TestFlight delivery.