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

If your app does not set a Kotlin version, the plugin sets Kotlin 2.3.20. If you set one yourself, the plugin keeps it. To set it explicitly, use expo-build-properties:

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

The Mapp Android SDK requires a Kotlin 2.3 compiler.

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.

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.