Expo Integration Guide

Since version 2.0.0, the Mapp Intelligence React Native SDK supports Expo Prebuild and Continuous Native Generation (CNG) through a config plugin. You add the plugin to your Expo configuration, and Expo applies the required native setup every time it generates the android and ios folders.

Warning

Expo Go is not supported. The SDK contains native Android and iOS code that Expo Go cannot load. Use a development build (expo-dev-client) instead.

Requirements

The Expo integration is validated with the following setup:

Other Expo SDK versions have not been validated. Your React Native version must stay within the SDK's supported range >=0.84.0 <0.87.0.

Step 1: Install the packages

From your Expo application directory, install the development client and the SDK:

npx expo install expo-dev-client
npm install mapp-intelligence-reactnative-plugin

With Yarn, install the SDK with yarn add mapp-intelligence-reactnative-plugin.

Step 2: Register the config plugin

Add mapp-intelligence-reactnative-plugin to the plugins array in app.json:

{
  "expo": {
    "plugins": ["mapp-intelligence-reactnative-plugin"]
  }
}

If your app already has plugins, append the package name to the existing array. For app.config.js or app.config.ts, add the same entry to the returned expo.plugins array.

The plugin has no options. It only adjusts the generated Android Kotlin configuration. It makes no changes to Android manifests or to the generated iOS project, and the SDK needs no permissions, Info.plist entries, or manual Xcode files.

Kotlin version

The plugin does not set a Kotlin version itself. If you set one, the plugin applies it to the Gradle build. Otherwise, Expo’s default applies. The Mapp Android SDK requires a Kotlin 2.3 compiler, so set it explicitly if your Expo SDK uses an older default. Use expo-build-properties:

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "kotlinVersion": "2.3.20"
          }
        }
      ],
      "mapp-intelligence-reactnative-plugin"
    ]
  }
}

Note

The plugin requires a Groovy root build.gradle, which is the Expo default. With a Kotlin DSL build script, the prebuild stops with an error. In that case, configure the Kotlin plugin version in the build script yourself.

iOS scene support for Expo SDK 57

If you build an Expo SDK 57 app with Xcode 27 for iOS 27, enable scene support in expo-build-properties. This requires Expo 57.0.23 or later and an up-to-date expo-build-properties package:

["expo-build-properties", { "ios": { "enableSceneSupport": true } }]

Merge the option into your existing expo-build-properties entry. Remove it after upgrading to Expo SDK 58, which enables scenes by default.

Step 3: Generate the native projects

Check that the Expo configuration resolves without errors:

npx expo config --type public

Then run a clean prebuild:

npx expo prebuild --clean

Prebuild applies the config plugin, and React Native autolinking adds the SDK to both native projects. You can repeat clean prebuilds safely. Keep any other native settings in your Expo configuration or in config plugins, because a clean prebuild regenerates the android and ios folders.

Step 4: Build and run the development app

npx expo run:android
npx expo run:ios

After the development app is installed, start Metro for it:

npx expo start --dev-client

Open the installed development app, not Expo Go.

Step 5: Initialize the SDK

The JavaScript and TypeScript API is identical to a React Native CLI app. Initialize the SDK as described in Installation & initialization, then verify that it works:

import { MappIntelligencePlugin } from 'mapp-intelligence-reactnative-plugin';

const initialized = await MappIntelligencePlugin.isInitialized();

if (!initialized) {
  throw new Error('Mapp Intelligence did not initialize');
}

await MappIntelligencePlugin.trackPage('Application started');

Test both the Android and the iOS development build.

When to rebuild

Run npx expo prebuild --clean again and rebuild the development app after you install or upgrade the SDK, or change native Expo configuration. JavaScript-only changes need only a Metro reload.

Migrating an existing app

If you already use the SDK in a React Native CLI app, or want to convert a CLI app to Expo Prebuild, see Migrating from 1.1.3 to 2.0.0.