---
title: "Installation & initialization"
slug: "react-integration-and-configuration"
updated: 2026-09-28T12:44:52Z
published: 2026-09-28T12:44:52Z
canonical: "docs.mapp.com/react-integration-and-configuration"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation & initialization

This section describes the installation and initialization of the React Native Software Development Kit and covers installation, initialization, and optional configuration.

> [!NOTE]
> Note
> 
> This page describes the setup for React Native CLI apps. For Expo apps, see [Expo Integration Guide](/docs/en/expo-integration-guide-react-native-intelligence). The initialization and tracking code is the same for both.

## Installation

To install the Mapp Intelligence plugin for the React Native application, run the following command in the terminal from the application root directory:

**Using npm:**

```shell
npm install mapp-intelligence-reactnative-plugin --save
```

**Using Yarn:**

```shell
yarn add mapp-intelligence-reactnative-plugin
```

React Native autolinking adds the Android and iOS implementations. Do not add the package manually to `settings.gradle`, `MainApplication`, or the Xcode project.

For iOS, you also need to install the **CocoaPods** dependencies:

```shell
cd ios
pod install
cd ..
```

Then rebuild the native apps:

```shell
npx react-native run-android
npx react-native run-ios
```

> [!WARNING]
> Warning
> 
> A Metro reload does not install or update native SDK code. Rebuild and reinstall the app after adding or upgrading the plugin.

---

## Initialization

After installing the plugin, configure and initialize it at the application start:

```javascript
import { MappIntelligencePlugin, LogLevel, ExceptionType } from 'mapp-intelligence-reactnative-plugin';

// Required steps
await MappIntelligencePlugin.setAnonymousTracking(false);

await MappIntelligencePlugin.initWithConfiguration(
   [TRACK_IDS],
   TRACK_DOMAIN
);

// Build the configuration
await MappIntelligencePlugin.build();
```

To check that the SDK is ready, call `isInitialized()` after `build()` resolves:

```javascript
const initialized = await MappIntelligencePlugin.isInitialized();
```

---

## Optional configuration

You can configure additional settings depending on your requirements:

```javascript
await MappIntelligencePlugin.setLogLevel(LogLevel.all);
await MappIntelligencePlugin.setBatchSupportEnabled(false);
await MappIntelligencePlugin.setBatchSupportSize(150);
await MappIntelligencePlugin.setRequestInterval(1);
await MappIntelligencePlugin.setSendAppVersionInEveryRequest(true);
await MappIntelligencePlugin.setEnableBackgroundSendout(true);
await MappIntelligencePlugin.setExceptionLogLevel(ExceptionType.all);
await MappIntelligencePlugin.setEnableUserMatching(false);
```

> [!NOTE]
> Note
> 
> `setEnableBackgroundSendout` is available on iOS only.

---

## Exception tracking (optional)

To set up a global error handler in a React Native application using the Mapp Intelligence plugin, follow these steps:

**Import required function:**

```javascript
import { setGlobalErrorHandler } from 'mapp-intelligence-reactnative-plugin';
```

**Define error handling function (optional):**

```javascript
const showError = (error: Error, isFatal: boolean) => {
  Alert.alert(
    'Unexpected error occurred',
    `Error: ${isFatal ? 'Fatal:' : ''} ${error.name} ${error.message}

    We have reported this to our team! Please close the app and start again!`,
    [
      {
        text: 'Close',
        onPress: () => {
          // Optionally, you can close or restart the app
        },
      },
    ]
  );
};
```

**Set global error handler:**

```javascript
setGlobalErrorHandler((error: Error, isFatal: boolean) => {
  showError(error, isFatal);
});
```

**Register component:**

```javascript
import { Alert, AppRegistry } from 'react-native';
AppRegistry.registerComponent(appName, () => App);
```

---

## Data format & limits

Mapp Intelligence supports the UTF-8 standard.

- A request may not be larger than 7KB.
- Input is case-sensitive.

Parameters can have the data type **text** or **figure**:

- **Text parameters**: maximum of 255 characters per value.
- **Figure parameters**: range of decimal(12,2)

(−9999999999.99 to 9999999999.99)