File Based Initialization

Overview

Starting with v7.0.0., the MoEngage Capacitor 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.

Script-based Initialization

This approach outlines how to use the form-based interface to generate a validated code snippet for initialization and to access module-specific configurations. Follow these steps to generate your initialization script:

Navigate to the Initialization Website.
Configure the values based on your application requirements. Refer to the Configuration Parameters tables below.
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

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 Data Center values.
	`com_moengage_core_environment`	String	Supported values are: `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. For example, `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 moengage.xml file in your Capacitor Android project at 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 Configurations

Category	Plist Key	Type	Description
Core	`WorkspaceId`	String	Specifies your App ID. It is a Mandatory field.
	`IsSdkAutoInitialisationEnabled`	Boolean	Set to `true` to enable SDK auto initialisation.
	`DataCenter`	Integer	Specifies the Data Center value. This is a Mandatory field. The default value is 1. For more info, refer to Data Center values.
	`IsTestEnvironment`	String / Boolean	Customer selected option (`true`/`false`). Default value is: `$(SWIFT_ACTIVE_COMPILATION_CONDITIONS)`.
	`CustomBaseDomain`	String	Specifies the base custom proxy domain to route SDK network traffic through your own subdomain.
	`IntegrationPartner`	String	Specifies your integration partner. For example, `segment` or `mparticle`. Default value: none.
	`AppGroupName`	String	Specifies the App Group name used for sharing SDK data. Default value: `""`.
Logs	`IsLoggingEnabled`	Boolean	Set to true to enable SDK logs.
	`Loglevel`	Integer	`0` to `5`. Default: `2`.
Security	`IsStorageEncryptionEnabled`	Boolean	Enables local storage encryption. Default value: `false`.
	`KeychainGroupName`	String	Specifies the keychain group name used for storing encryption keys. This is a mandatory field if `IsStorageEncryptionEnabled` is `true`. Default value: `""`.
	`IsNetworkEncryptionEnabled`	Boolean	Enables payload encryption. Default: `false`.
	`EncryptionEncodedTestKey`	String	Dashboard auto-populated string. Used if `IsNetworkEncryptionEnabled` is `true`.
	`EncryptionEncodedLiveKey`	String	Dashboard auto-populated string. Used if `IsNetworkEncryptionEnabled` is `true`.
Sync	`AnalyticsEnablePeriodicFlush`	Boolean	Enables periodic data flush. Default: `true`.
	`AnalyticsPeriodicFlushDuration`	Integer	Flush interval in seconds. Default: `60`.
In-App	`InAppDisplaySafeAreaInset`	Real	Decimal value representing safe area padding. Default: `0`.
	`InAppShouldProvideDeeplinkCallback`	Boolean	If `true`, provides callback on deeplink. Default: `false`.

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 your project’s Info.plist (found in ios/App/App/Info.plist).
Create a new Top-Level Key named MoEngage of type Dictionary.
Add the configuration file content generated in the Initialization Website.

The key IsSdkAutoInitialisationEnabled uses the British spelling (‘s’). Ensure you use the exact key name shown below, 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, you need to trigger the initialization in both your native wrappers and your Capacitor framework.

Android Native Setup

Before initializing the SDK from JavaScript, initialise the native module in your Android Application class. Add the following to android/app/src/main/java\<your\_package\>/MainApplication.java (or .kt) inside onCreate(). File-based init (reads configuration from res/values/ XML, e.g. moengage.xml):

import com.moengage.capacitor.MoEInitializer;

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

import com.moengage.capacitor.MoEInitializer

override fun onCreate() {
    super.onCreate()
    // ... existing code
    MoEInitializer.initialiseDefaultInstance(this)
}

iOS Native Setup

Ensure your AppDelegate.swift triggers the SDK initialization using the default instance method, allowing it to read from your Info.plist.

import UIKit
import Capacitor

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    
    var window: UIWindow?
    
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        MoECapacitorInitializer.sharedInstance.initializeDefaultInstance() 
        
        return true
    }
}

Initialize Capacitor Component

After native Android setup, initialize the plugin from your app entry or root component (e.g., app.component.ts, main.ts, or index.ts/js) o the bridge and initConfig are registered before you call other MoEngage Capacitor APIs.

import { MoECapacitorCore } from 'capacitor-moengage-core';

await MoECapacitorCore.initialize({
  appId: 'YOUR_WORKSPACE_ID',
  initConfig: {
    analyticsConfig: {
      shouldTrackUserAttributeBooleanAsNumber: true,
    },
    // Optional — omit if you do not need push click callbacks from JS
    pushConfig: {
      shouldDeliverCallbackOnForegroundClick: true,
    },
  },
  // Optional — queues some callbacks until app returns to foreground
  lifecycleAwareCallbackEnabled: false,
});

Migration and Precedence

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

Environments (Test vs. Live)

You can configure Test/Live environments within these files.

Android: Use the key <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 Capacitor 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 Capacitor Component

Migration and Precedence

Environments (Test vs. Live)