> ## Documentation Index
> Fetch the complete documentation index at: https://moengage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# File Based Initialization

## Overview

<Info>
  Starting with [v7.0.0.](/docs/release-notes/sdks/capacitor#core-7-0-0), the MoEngage Capacitor SDK supports file-based initialization.
</Info>

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:

1. Navigate to the [Initialization Website.](https://app-cdn.moengage.com/sdk/integration/config/index.html)
2. Configure the values based on your application requirements. Refer to the Configuration Parameters tables below.
3. 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`.

<Accordion title="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](#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. |
</Accordion>

<Warning>
  **Troubleshooting**

  If the XML file is missing or the `com_moengage_core_workspace_id` is empty, the SDK will throw a `ConfigurationMismatchError`.
</Warning>

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

<Accordion title="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](#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`. |
</Accordion>

### 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](http://dashboard-01.moengage.com) |
| 2 | [dashboard-02.moengage.com](http://dashboard-02.moengage.com) |
| 3 | [dashboard-03.moengage.com](http://dashboard-03.moengage.com) |
| 4 | [dashboard-04.moengage.com](http://dashboard-04.moengage.com) |
| 5 | [dashboard-05.moengage.com](http://dashboard-05.moengage.com) |
| 6 | [dashboard-06.moengage.com](http://dashboard-06.moengage.com) |

### Update Info.plist

1. Open your project's `Info.plist` (found in `ios/App/App/Info.plist`).
2. Create a new Top-Level Key named `MoEngage` of type `Dictionary`.
3. Add the configuration file content generated in the [Initialization Website.](https://app-cdn.moengage.com/sdk/integration/config/index.html)

<Warning>
  The key `IsSdkAutoInitialisationEnabled` uses the British spelling ('s'). Ensure you use the exact key name shown below, or initialization will fail.
</Warning>

**XML Snippet Representation:**

<CodeGroup>
  ```xml XML theme={null}
  <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>
  ```
</CodeGroup>

## 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):

<CodeGroup>
  ```javascript Java theme={null}
  import com.moengage.capacitor.MoEInitializer;

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

  ```kotlin Kotlin theme={null}
  import com.moengage.capacitor.MoEInitializer

  override fun onCreate() {
      super.onCreate()
      // ... existing code
      MoEInitializer.initialiseDefaultInstance(this)
  }
  ```
</CodeGroup>

### iOS Native Setup

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

<CodeGroup>
  ```swift Swift wrap theme={null}

  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
      }
  }
  ```
</CodeGroup>

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  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,
  });
  ```
</CodeGroup>

## Migration and Precedence

To migrate from manual code-based initialization to the file-based approach, refer [here](/docs/developer-guide/capacitor-sdk/sdk-integration/basic/sdk-initialization/file-based-initlialization/migration-and-precedence).

## 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/>`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.