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

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

The package is available on npm: react-native-mapp-plugin

For iOS, install the CocoaPods dependencies:

cd ios && pod install

2. Android: configure Gradle

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

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

Android:

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

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

iOS:

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

5. Verify initialization

// 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():

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

• Configure push notifications → Push Notifications

• Set up in-app messaging → In-App Messaging

• Track user attributes and events → User Data