---
title: "Get Started"
slug: "getting-started-react-native-engage"
updated: 2026-09-03T14:21:54Z
published: 2026-09-03T14:21:54Z
canonical: "docs.mapp.com/getting-started-react-native-engage"
---

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

# Get Started

## Goal

Install the Mapp Engage React Native Plugin and initialize the SDK in your application.

## Prerequisites

- React Native 0.84 or later
- React 19.2.3 or later
- Android: `google-services.json` from your Firebase project placed in `android/app/`
- iOS: CocoaPods installed
- SDK credentials (sdkKey, server, appID, tenantID) — available in the Mapp Engage Admin Panel under SDK Integration settings, or provided by your Mapp account team

## Procedure

### 1. Install the package

```bash
npm install react-native-mapp-plugin --save
```

The package is available on npm: [react-native-mapp-plugin](https://www.npmjs.com/package/react-native-mapp-plugin)

For iOS, install the CocoaPods dependencies:

```bash
cd ios && pod install
```

### 2. Android: configure Gradle

In `android/app/build.gradle`, ensure the Google Services plugin is applied and multiDex is enabled:

```groovy
android {
    defaultConfig {
        multiDexEnabled true
    }
}
apply plugin: 'com.google.gms.google-services'
```

### 3. iOS: configure Xcode capabilities

1. Open your project in Xcode.
2. Under **Signing & Capabilities**, add **Push Notifications**.
3. Add **Background Modes** and enable **Remote notifications**.
4. Create an `AppoxeeConfig.plist` file and add it to your application target:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>inapp</key>
    <dict>
        <key>custom_fields</key>
        <array>
            <string>customString</string>
            <string>customNumber</string>
            <string>customDate</string>
        </array>
        <key>media_timeout</key>
        <integer>5</integer>
    </dict>
    <key>sdk</key>
    <dict>
        <key>app_id</key>
        <string>your-app-id</string>
        <key>dmc_system_id</key>
        <integer>your-dmc-id</integer>
        <key>sdk_key</key>
        <string>your-sdk-key</string>
        <key>is_eu</key>
        <true/>
        <key>open_landing_page_inside_app</key>
        <false/>
        <key>jamie_url</key>
        <string>your-inapp-server-url</string>
        <key>apx_open_url_internal</key>
        <string>YES</string>
    </dict>
</dict>
</plist>
```

### 4. Initialize the SDK

Call `Mapp.engage()` as the first SDK call in your application entry point, before rendering any components. Since 2.0.0, `engage()` returns a promise — await it before calling APIs that depend on the native Mapp singleton, such as `isReady()` or `isDeviceRegistered()`.

**Android**

```javascript
import { Mapp } from 'react-native-mapp-plugin';

await Mapp.engage(
  'your-sdk-key',
  '',               // legacy field — leave empty
  'your-server',
  'your-app-id',
  'your-tenant-id'
);
```

**iOS**

```javascript
// On iOS, only the server parameter is used
await Mapp.engage('', '', 'your-server', '', '');
```

### 5. Verify initialization

```javascript
// Check if the SDK is ready
const ready = await Mapp.isReady();
console.log('SDK ready:', ready);

// Check if the device is registered with the Mapp backend
const registered = await Mapp.isDeviceRegistered();
console.log('Device registered:', registered);
```

On Android, listen for initialization completion as an alternative to polling `isReady()`:

```javascript
Mapp.onInitCompletedListener().then(() => {
  console.log('Mapp SDK initialized');
});
```

## Result

`Mapp.isReady()` returns `true` and `Mapp.isDeviceRegistered()` returns `true`. The device is registered with the Mapp backend and push notification delivery is active.

## Next Steps

- [Push Notifications](/docs/en/push-notifications-react-native-engage) — platform-specific push setup, deep links, and geofencing
- [In-App Messaging](/docs/en/in-app-messaging-react-native-engage) — triggered messages, inbox, and rich messages
- [User Data](/docs/en/user-data-react-native-engage) — alias, attributes, tags, and custom events