File Based Initialization

Overview

Starting with v12.0.0, the React Native SDK supports file-based initialization.

To streamline the integration process and minimize initialization errors, MoEngage supports Script-Based Initialization. This approach allows you to manage App IDs and configuration settings directly within native configuration files, keeping them separate from your application logic. This article outlines how you can use the form-based interface to generate a validated code snippet for initialization and access module-specific configurations.

Alternatively, the SDK can be initialized manually. If you require this approach, please refer to the guide on Framework Initialization.

Script-based Initialization

Follow these steps to generate your initialization script:

Visit the Config Generator

Navigate to the Initialization Website.

Configure Parameters

Configure the values based on your application requirements. Refer to the Configuration Parameters tables below for:

Android
iOS

Generate

Click Generate Code at the bottom of the form.

Android Configuration (XML)

For Android, initialization is handled by placing an XML configuration file in the application’s resource directory.

Android Configuration Reference

Below is the comprehensive list of keys available for moengage.xml.

Android Configuration Details

Category	XML Key Name	Type	Description
Core	`com_moengage_core_workspace_id`	String	Specifies your App ID. This field is mandatory.
	`com_moengage_core_file_based_initialisation_enabled`	Boolean	Set to `true` to enable this feature.
	`com_moengage_core_data_center`	Integer	Default: `1`. For more info, refer to Data Center values.
	`com_moengage_core_environment`	String	Supported values: `default`, `live`, or `test`.
	`com_moengage_core_custom_base_domain`	String	Specifies the base custom proxy domain to route SDK network traffic through your own subdomain.
	`com_moengage_core_integration_partner`	String	Specifies the core integration partner (e.g., `segment` or `mparticle`).
Push	`com_moengage_push_notification_small_icon`	Drawable	Resource ID for small icon.
	`com_moengage_push_notification_large_icon`	Drawable	Resource ID for large icon.
	`com_moengage_push_notification_color`	Color	Notification accent color.
	`com_moengage_push_notification_token_retry_interval`	Integer	Retry interval (in seconds) for token registration.
	`com_moengage_push_kit_registration_enabled`	Boolean	If `true`, SDK registers for push token.
Logs	`com_moengage_core_log_level`	Integer	`0` (No Log) to `5` (Verbose). Default: `3`.
	`com_moengage_core_log_enabled_for_release_build`	Boolean	If `true`, prints logs in release builds.
Security	`com_moengage_core_storage_encryption_enabled`	Boolean	Enables local storage encryption.
	`com_moengage_core_network_encryption_enabled`	Boolean	Enables payload encryption over the network.
Sync	`com_moengage_core_periodic_data_sync_enabled`	Boolean	Enables periodic data sync in the foreground.
	`com_moengage_core_background_data_sync_enabled`	Boolean	Enables periodic data sync in the background.
In-App	`com_moengage_inapp_show_in_new_activity_enabled`	Boolean	Required for specific TV/Android setups.

TroubleshootingIf the XML file is missing or the com_moengage_core_workspace_id is empty, the SDK will throw a ConfigurationMismatchError.

Add Configuration File

Place the generated file in android/app/src/main/res/values/.

iOS Configuration (Info.plist)

For iOS, initialization is handled by adding a configuration dictionary to your Info.plist.

iOS Configuration Reference

Below is the comprehensive list of keys available for the MoEngage dictionary.

iOS Configuration Details

Category	Plist Key	Type	Description
Core	`WorkspaceId`	String	Specifies your App ID. Mandatory.
	`IsSdkAutoInitialisationEnabled`	Boolean	Set to `true` to enable SDK auto-initialisation.
	`DataCenter`	Integer	Mandatory. Default: `1`. Refer to Data Center values.
	`IsTestEnvironment`	String / Boolean	Default: `$(SWIFT_ACTIVE_COMPILATION_CONDITIONS)`.
	`CustomBaseDomain`	String	Specifies the custom proxy domain subdomain.
	`IntegrationPartner`	String	Integration partner (e.g., `segment` or `mparticle`).
	`AppGroupName`	String	App Group name for sharing SDK data.
Logs	`IsLoggingEnabled`	Boolean	Set to `true` to enable SDK logs.
	`Loglevel`	Integer	`0` to `5`. Default: `2`.
Security	`IsStorageEncryptionEnabled`	Boolean	Enables local storage encryption.
	`KeychainGroupName`	String	Mandatory if storage encryption is enabled.
	`IsNetworkEncryptionEnabled`	Boolean	Enables payload encryption.
	`EncryptionEncodedTestKey`	String	Dashboard auto-populated string for Test environment.
	`EncryptionEncodedLiveKey`	String	Dashboard auto-populated string for Live environment.
Sync	`AnalyticsEnablePeriodicFlush`	Boolean	Enables periodic data flush. Default: `true`.
	`AnalyticsPeriodicFlushDuration`	Integer	Flush interval in seconds. Default: `60`.
In-App	`InAppDisplaySafeAreaInset`	Real	Safe area padding padding value.
	`InAppShouldProvideDeeplinkCallback`	Boolean	Provides callback on deeplink if `true`.

Data Center Values

Configure the integer corresponding to your region. Incorrect values will result in data loss.

Data Center	Dashboard host
1	dashboard-01.moengage.com
2	dashboard-02.moengage.com
3	dashboard-03.moengage.com
4	dashboard-04.moengage.com
5	dashboard-05.moengage.com
6	dashboard-06.moengage.com

Update Info.plist

Open Plist

Open your project’s Info.plist (found in ios/ProjectName/).

Create MoEngage Dictionary

Create a new Top-Level Key named MoEngage of type Dictionary.

Configure

Add the configuration file content generated in the Initialization Website.

Warning The key IsSdkAutoInitialisationEnabled uses the British spelling (‘s’). Ensure you use the exact key name, or initialization will fail.

XML Snippet Representation:

<key>MoEngage</key>
<dict>
    <key>WorkspaceId</key>
    <string>YOUR_WORKSPACE_ID</string>
    <key>IsTestEnvironment</key>
    <string>$(SWIFT_ACTIVE_COMPILATION_CONDITIONS)|$(GCC_PREPROCESSOR_DEFINITIONS)</string>
    <key>DataCenter</key>
    <integer>1</integer>
    <key>CustomBaseDomain</key>
    <string>data.example.com</string>
    <key>IsLoggingEnabled</key>
    <true/>
</dict>

Framework Level Initialization

After you configure the native files, the initialization code in your hybrid framework is simplified.

Android Native Setup

Add the following code to android/app/src/main/java/com/your_app/MainApplication.java (or .kt) inside the onCreate() method.

Kotlin
Java

import com.moengage.react.MoEInitializer

override fun onCreate() {
  super.onCreate()
  MoEInitializer.initializeDefaultInstance(application)
}

import com.moengage.react.MoEInitializer;

@Override
public void onCreate() {
  super.onCreate();
  // ... existing code
  MoEInitializer.INSTANCE.initializeDefaultInstance(this);
}

iOS Native Setup

Add the following code to your AppDelegate class inside the didFinishLaunchingWithOptions method.

Swift
Objective-C

import MoEngageSDK

override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
  // ... existing code
  MoEngage.sharedInstance.initializeDefaultInstance()
  return super.application(application, didFinishLaunchingWithOptions: launchOptions)
}

#import <MoEngageSDK/MoEngageSDK.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  // ... existing code
  [[MoEngageInitializer sharedInstance] initializeDefaultInstanceWithAdditionalReactConfig:[[MoEngageReactSDKDefaultInitializationConfig alloc] init]];
  return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

Initialize React-Native Component

Initialize the MoEngage Plugin in the App.js or App.ts of your application once the component is mounted.

TypeScript

import ReactMoE from 'react-native-moengage';
ReactMoE.initialize("YOUR_WORKSPACE_ID");

If you have a class-based component, you can initialize in the render() or componentDidMount().

Migration and Precedence

To migrate from manual code-based initialization to file-based approach, refer here.

Environments (Test vs. Live)

You can configure Test/Live environments within these files:

Android: Use <string name="com_moengage_core_environment">test</string>.
iOS: Use <key>IsTestEnvironment</key> <true/>.

​Overview

​Script-based Initialization

​Android Configuration (XML)

​Android Configuration Reference

​Add Configuration File

​iOS Configuration (Info.plist)

​iOS Configuration Reference

​Data Center Values

​Update Info.plist

​Framework Level Initialization

​Android Native Setup

​iOS Native Setup

​Initialize React-Native Component

​Migration and Precedence

​Environments (Test vs. Live)

Overview

Script-based Initialization

Android Configuration (XML)

Android Configuration Reference

Add Configuration File

iOS Configuration (Info.plist)

iOS Configuration Reference

Data Center Values

Update Info.plist

Framework Level Initialization

Android Native Setup

iOS Native Setup

Initialize React-Native Component

Migration and Precedence

Environments (Test vs. Live)