File Based Initialization

Overview

Starting with v10.3.0, the Flutter 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.

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:
- Android
- iOS
Click Generate Code at the bottom of the form.

Step 1: 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 file in android/app/src/main/res/values/.

Step 2: 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/Runner/ ).
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>

Step 3: Framework Level Initialization

After you configure the native files, the initialization code in your hybrid framework is simplified. Create MoEngageFlutter(YOUR_Workspace_ID) object and in the project’s App Widget call initialise() of MoEngageFlutter plugin in the initState() the method as shown below:

import 'package:moengage_flutter/moengage_flutter.dart';
final MoEngageFlutter _moengagePlugin = MoEngageFlutter(YOUR_Workspace_ID);
@override
void initState() {
  super.initState();
  initPlatformState();
  _moengagePlugin.initialise();
}

Step 4: Migration and Precedence

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

Step 5: 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

​Step 1: Android Configuration (XML)

​Android Configuration Reference

​Add Configuration File

​Step 2: iOS Configuration (Info.plist)

​iOS Configuration Reference

​Data Center Values

​Update Info.plist

​Step 3: Framework Level Initialization

​Step 4: Migration and Precedence

​Step 5: Environments (Test vs. Live)

Overview

Step 1: Android Configuration (XML)

Android Configuration Reference

Add Configuration File

Step 2: iOS Configuration (Info.plist)

iOS Configuration Reference

Data Center Values

Update Info.plist

Step 3: Framework Level Initialization

Step 4: Migration and Precedence

Step 5: Environments (Test vs. Live)