Configure the MoEngage Expo SDK

Overview

This guide covers the parameters you can use to configure the MoEngage SDK. All plugin-level configuration is done within your app.json or app.config.js file. Core SDK credentials are placed in separate platform-specific files.

You must complete the installation guide before you configure the SDK.

Plugin-Managed Native Configuration

To ensure a reliable and streamlined setup, the MoEngage Expo plugin manages native project configurations automatically. This approach reduces the potential for manual errors by handling platform-specific requirements during the prebuild process. Key automations include:

Applying Critical Settings: The plugin automatically adds required settings, such as the Android backup exclusion rules, to ensure data integrity.
Eliminating Manual File Edits: Direct modification of native files like AndroidManifest.xml (for Android) or Info.plist (for iOS) is not necessary.

SDK Initialization Configuration (XML and Plist files)

As specified in the configFilePath property, your core MoEngage credentials and SDK settings do not go in app.json. Instead, they are defined in separate files for each platform.

For Android: Generate an XML file (e.g., android_initialisation_config.xml).
For iOS: Generate a Plist file (e.g., MoEngage-Config.plist).

SDK Configuration Parameters

The following tables detail the available properties for these files.

Android
iOS

Android SDK Configuration

Section	Field Name	Description
Core	Moengage Workspace ID	This field denotes the unique identifier that links your application to a specific workspace within your MoEngage dashboard.
Core	Moengage Project ID	This field denotes the unique identifier associated with a specific project if you have Portfolio feature enabled for your workspace.
Core	Moengage Data Center	This field denotes the data center based on the dashboard URL. Refer here for more details.
Core	MoengageEnvironment	This field denotes the environment for data reporting, such as LIVE for the live application or TEST for development, to prevent test data from affecting production analytics.
Core	Custom Proxy Domain	This field denotes the base custom proxy domain used to route SDK network traffic through your own subdomain. (Key: `com_moengage_core_custom_base_domain`)
Core	Enable Logging for Release build	This field denotes whether to activate SDK logging in the production version of your app. It is recommended to disable this in release builds to improve performance and prevent exposure of sensitive data.
Core	Log Level	This field denotes the verbosity of the logs generated by the SDK, typically ranging from detailed (VERBOSE = 0) to minimal (ERROR = 3), for debugging purposes.
Core	Integration Partner	This field denotes the name of any third-party integration partner you are using, which helps in attributing user acquisition or specific events to that partner.
Core	Cache Connection	This field denotes the configuration for how the SDK caches data locally before sending it to MoEngage servers, helping to manage network usage and offline tracking.
Data Tracking	Track Device Information	This field denotes whether the SDK should track standard device attributes such as the device model, OS version, GAID, and app version.
Data Tracking	Enable Carrier Tracking	This field denotes whether the SDK should collect and send the user’s mobile carrier information (e.g., Verizon, T-Mobile) for segmentation.
Data Tracking	Enable Screen Filtering by Package	This field denotes whether to enable the package-based filtering specified in Screen Tracking Whitelisted Packages.
Data Tracking	Screens to Exclude from Tracking	This field denotes a comma-separated list of Android Activity names to be excluded from automatic screen tracking, preventing data collection from sensitive or irrelevant screens.
Data Tracking	Enable Background Data Sync	This field denotes whether the SDK is permitted to synchronize data with MoEngage servers while the application is running in the background.
Data Tracking	Enable Periodic Data Sync	This field denotes the time interval in milliseconds at which the SDK syncs batched data with MoEngage servers if periodic sync is enabled.
Push Notification	Push Token Retry Interval(s)	This field denotes the time interval in seconds that the SDK should wait before attempting to resend a push notification that failed to be delivered.
Push Notification	Push Notification Small Icon	This field denotes the resource name of the drawable to be used as the small icon for all push notifications from your app.
Push Notification	Push Notification Large Icon	This field denotes the resource name of the drawable to be used as the large icon for push notifications.
Push Notification	Push Notification Color	This field denotes the hexadecimal color code (e.g., #FFFFFF) used to accent push notifications, affecting elements like the app name and action buttons.
Push Notification	Group Multiple Notifications in Drawer	This field denotes the key used to group multiple notifications from your app into a single, stacked notification in the system tray.
Push Notification	Enable Push Notification Back Stack Building	This field denotes whether tapping a notification should rebuild the app’s task stack, ensuring proper back-button navigation.
Push Notification	Enable Notification Large Icon Display	This field denotes whether to show the specified large icon in push notifications.
Push Notification	Enable Heads-Up Notification	This field denotes whether to allow high-priority notifications to appear as a floating “heads-up” banner at the top of the screen.
Push Notification	Configure FCM Registration	This field denotes the server key from your Firebase Cloud Messaging (FCM) project, which is required to send push notifications to Android devices.
Push Notification	Configure Huawei Push Kit Registration	This field denotes the app secret key from your Huawei Mobile Services (HMS) project, required for sending push notifications to Huawei devices.
Push Notification	Enable RTT Background Sync	This field denotes whether to enable Real-Time Triggers (RTT) background sync, allowing for more immediate campaign actions based on user behavior.
In-apps	Screens to Suppress In-Apps	This field denotes a comma-separated list of Android Activity names on which in-app messages should not be displayed.
In-apps	Show In-App in New Activity	This field denotes whether in-app messages should be displayed within a new, dedicated Android Activity instead of overlaying the current one.
Cards	Cards Placeholder Image	This field denotes a URL for a placeholder image that is displayed while the actual Card content is loading.
Cards	Cards Empty Inbox Image	This field denotes a URL for an image to be displayed when the user’s Card inbox is empty.
Cards	Cards Date Format	This field denotes the desired date format (e.g., “dd-MMM-yyyy”) for displaying timestamps on Card elements in the UI.
Cards	Enable Swipe to Refresh the Cards	This field denotes whether users can pull down on the Card inbox screen to refresh its content.
Security	Enable Storage Encryption	This field denotes whether to encrypt the MoEngage data that is stored locally on the user’s device, enhancing data security.
Security	Enable Network Encryption	This field denotes whether to encrypt the data transmitted between the SDK and MoEngage’s servers, securing data in transit.
Security	Enable JWT Authorisation	This field denotes whether to enable JSON Web Token (JWT) based authorization for authenticating requests from the SDK to the MoEngage backend.

iOS SDK Configuration

Section	Field Name	Description
Core	MoEngage Workspace ID	This field denotes the unique identifier that links your application to a specific workspace within your MoEngage dashboard.
Core	Moengage Project ID	This field denotes the unique identifier associated with a specific project if you have Portfolio feature enabled for your workspace.
Core	Moengage Data Center	This field denotes the geographical location of the MoEngage server (e.g., 1 for US, 2 for EU) where your app’s data will be stored and processed.
Core	MoengageEnvironment	This field denotes the environment for data reporting, such as PROD for the live application or DEV for development, to prevent test data from affecting production analytics. By default, the environment is picked from the build configuration.
Core	Custom Proxy Domain	This field denotes the base custom proxy domain used to route SDK network traffic through your own subdomain. (Key: `CustomBaseDomain`)
Core	Enable Logging for Release & Debug build	This field denotes whether to activate SDK logging in your app’s production version. It is recommended that you disable this in release builds.
Core	Integration Partner	This field denotes the name of any third-party integration partner, which helps in attributing user acquisition or specific events to that partner.
Core	App Group Name	This field denotes the App Group ID, which allows the main app to share data with its associated extensions, such as Notification Service Extensions.
Data Tracking	Enable Periodic Data Sync	This field denotes whether to batch and send tracked data to MoEngage at a set interval rather than in real time. Enabling this by default can optimize battery and network usage.
In-apps	Padding for Inapp	This field denotes the amount of padding (in points) as a safe area to apply around the content of in-app messages to control their spacing and layout.
In-apps	Provide Deeplink Call back	This field denotes whether to provide a callback method to the host application for custom handling of deep links triggered from in-app messages.
Security	Enable Storage Encryption	This field denotes whether to encrypt the MoEngage data that is stored locally on the user’s device, enhancing data security. Encryption is not enabled by default.
Security	Enable Network Encryption	This field denotes whether to encrypt the data transmitted between the SDK and MoEngage’s servers, securing data in transit. Encryption is not enabled by default.
Security	JWT Authorization Enabled	This field denotes whether to enable JSON Web Token (JWT) based authorization for authenticating requests from the SDK to the MoEngage backend.

Configuration parameters

Add the properties listed below inside the react-native-expo-moengage plugin entry in your app.json or app.config.js file. These parameters control the plugin’s build-time behavior, such as linking native modules and pointing to your configuration files.

Open your app.json or app.config.js file.
Add react-native-expo-moengage to the plugins array.

Android
iOS

[
        "react-native-expo-moengage",
        {
          "android": {
            "configFilePath": "assets/moengage/android_initilisation_config.xml",
            "smallIconPath": "assets/moengage/small_icon.png",
            "largeIconPath": "assets/moengage/large_icon.png",
            "disableMoEngageDefaultBackupFile": false,
            "includeFirebaseMessagingDependencies": true,
            "isExpoNotificationIntegration": true,
            "shouldIncludeMoEngageFirebaseMessagingService": true
          }
        }
]

Key	Description
configFilePath	Specifies the path to the configuration file (.xml) containing your core MoEngage SDK settings.
smallIconPath	Specifies the path to the small icon to be used in push notification.
largeIconPath	Specifies the path to the large icon to be used in push notification.
disableMoEngageDefaultBackupFile	MoEngage necessitates the exclusion of specific files during backup. This flag is designed to configure this process. If enabled, the configuration will be automatically included; otherwise, you need to add it manually. For more info, refer here.
includeFirebaseMessagingDependencies	The plugin includes the Firebase Cloud Messaging (FCM) library required for push.
isExpoNotificationIntegration	Set to true to ensure compatibility and correctly route push payloads when using the expo-notifications library alongside the MoEngage notification service.
shouldIncludeMoEngageFirebaseMessagingService	If enabled, the notification service is included by MoEngage; otherwise, you must pass the payload to the MoEngage SDK.

[
        "react-native-expo-moengage",
        {
          "apple": {
            "configFilePath": "assets/moengage/MoEngage-Config.plist",
            "pushNotificationImpressionTrackingEnabled": true,
            "richPushNotificationEnabled": true,
            "pushTemplatesEnabled": true,
            "deviceTriggerEnabled": true,
            "liveActivityTargetPath": "assets/moengage/LiveActivity"
          }
        }
      ],

Key	Description
configFilePath	Specifies the path to the MoEngage configuration plist file relative to the application project root path. The data in this plist file is added to the MoEngage key in the application’s Info.plist. If no path is provided, assets/moengage/MoEngage-Config.plist is assumed to be the path.
pushNotificationImpressionTrackingEnabled	Specifies whether to enable push notification delivery impression tracking. The default value is true if not provided.
richPushNotificationEnabled	Specifies whether to enable rich media content in push notifications. false if not provided.
pushTemplatesEnabled	Whether to enable push notification templates. False if not enabled. For more info, refer here.
deviceTriggerEnabled	Whether to enable device-triggered notifications. False if not enabled. For more info, refer here.
liveActivityTargetPath	Specifies the path to the Live Activity widget target files. It should include the widget’s UI and payload definitions and any additional resources required by the widget. For more info, refer here.

Configure iOS App Extensions with EAS Build

EAS Build automatically handles standard iOS app configurations. However, if your app uses features that require separate native targets, you must configure them in eas.json. This includes features like:

Notification Service Extensions (NSE): used for rich push and impression tracking.
Notification Content Extensions (NCE): used for Push templates or Live Activities.

To configure iOS app extensions, add the appExtensions key to the expo.extra.eas.build.experimental.ios object. This configuration ensures EAS Build can correctly compile and sign the additional native targets.

{
  "expo": {
    "extra": {
      "eas": {
        "build": {
          "experimental": {
            "ios": {
              "appExtensions": [
                {
                  "targetName": "MoEngageExpoRichPush",
                  "bundleIdentifier": "${YOUR Bundle Identifier}.MoEngageExpoRichPush",
                  "entitlements": {
                    "com.apple.security.application-groups": ["${YOUR AppGroup provided in apple.configFilePath}"]
                  }
                },
                {
                  "targetName": "MoEngageExpoPushTemplates",
                  "bundleIdentifier": "${YOUR Bundle Identifier}.MoEngageExpoPushTemplates",
                  "entitlements": {
                    "com.apple.security.application-groups": ["${YOUR AppGroup provided in apple.configFilePath}"]
                  }
                },
                {
                  "targetName": "MoEngageExpoLiveActivity",
                  "bundleIdentifier": "${YOUR Bundle Identifier}",
                  "entitlements": {
                    "com.apple.security.application-groups": ["${YOUR AppGroup provided in apple.configFilePath}"]
                  }
                }
              ]
            }
          }
        }
      }
    }
  }
}

Generate the native project files

After installing the package and adding the plugin entry, you must run the prebuild command. This command uses your configuration to generate the native Android and iOS directories for your project. Run the following command:

npx expo prebuild

Next steps

After you’ve added your configuration, the final step is to initialize the SDK in your app’s code.

Getting Started

SDKs

Configure the MoEngage Expo SDK

Overview

Plugin-Managed Native Configuration

SDK Initialization Configuration (XML and Plist files)

Configuration parameters

Configure iOS App Extensions with EAS Build

Generate the native project files

Next steps

Getting Started

SDKs

​Overview

​Plugin-Managed Native Configuration

​SDK Initialization Configuration (XML and Plist files)

​Configuration parameters

​Configure iOS App Extensions with EAS Build

​Generate the native project files

​Next steps

Overview

Plugin-Managed Native Configuration

SDK Initialization Configuration (XML and Plist files)

Configuration parameters

Configure iOS App Extensions with EAS Build

Generate the native project files

Next steps