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

# Manual Initialization

> Initialize the MoEngage iOS SDK in your AppDelegate using your Workspace ID and data center.

# Initializing MoEngage SDK

First, go to `Build Settings` of your `App Target` and ensure that **DEBUG** Preprocessor Macro is defined in `Debug` section as shown in the below image, if not present then add the same by entering `DEBUG=1` in `Debug` section:

![Sdkini](https://mintcdn.com/moengage/Jtvf10ggM77HdKvB/images/sdkini.png?fit=max\&auto=format\&n=Jtvf10ggM77HdKvB\&q=85\&s=0ade8f59e5ea7aad558987e9a24f6b87)

**For Swift Project**, In `App Target` `Build Settings` make sure **-DDEBUG** is added to `Debug` section in the `Other Swift Flags` as described in the image:

![Sdkini2](https://mintcdn.com/moengage/Jtvf10ggM77HdKvB/images/sdkini2.png?fit=max\&auto=format\&n=Jtvf10ggM77HdKvB\&q=85\&s=a4105826253083cd8a878a1dad84e35d)

* in to your MoEngage account, go to **Settings** in the left panel of the dashboard. Under General Settings, you will find your **Workspace ID**. Provide this Workspace ID along with the Datacenter while initializing the SDK with MoEngageSDKConfig instance . Use[***initializeDefaultTestInstance(\_:)***](https://moengage.github.io/ios-api-reference/Classes/MoEngage.html#/c:@M@MoEngageSDK@objc\(cs\)MoEngage\(im\)initializeDefaultTestInstance:)  and [***initializeDefaultLiveInstance(\_:)***](https://moengage.github.io/ios-api-reference/Classes/MoEngage.html#/c:@M@MoEngageSDK@objc\(cs\)MoEngage\(im\)initializeDefaultLiveInstance:) methods as shown below.

> [!NOTE]
>
> * **Breaking change in iOS SDK [11.0.0](https://moengage.com/docs/release-notes/sdks/ios.md#22nd-july-2026):** The SDK now enforces initialization before any public API use across all build configurations — Debug, Release, and TestFlight builds. Calling a public API before initializing the SDK triggers a `fatalError` rather than failing silently. Invoke `initializeDefaultTestInstance(_:)` or `initializeDefaultLiveInstance(_:)` before all other MoEngage API calls.
> * Starting with iOS SDK [11.0.0](https://moengage.com/docs/release-notes/sdks/ios.md#22nd-july-2026), `initializeDefaultLiveInstance(_:)` returns a typed task object instead of `Void`. Direct calls like the ones above compile unchanged. Chaining `.onSuccess { ... }` / `.onFailure { ... }` or calling the async `result()` method provides per-call visibility into success or failure.

```swift Swift wrap theme={null}
import MoEngageSDK
 func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  
      //Add your MoEngage Workspace ID and Data center.
      let sdkConfig = MoEngageSDKConfig(appId: "YOUR_WORKSPACE_ID", dataCenter: DATA_CENTER)
      // MoEngage SDK Initialization
      // Separate initialization methods for Dev and Prod initializations
      #if DEBUG
          MoEngage.sharedInstance.initializeDefaultTestInstance(sdkConfig)
      #else
         MoEngage.sharedInstance.initializeDefaultLiveInstance(sdkConfig)
      #endif
 
  //Rest of the implementation of method
  //-------
  return true
}
```

```objective-c Objective C wrap theme={null}
@import MoEngageSDK;
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
     //TODO: Add your MoEngage Workspace ID and Data center.
     MoEngageSDKConfig* sdkConfig = [[MoEngageSDKConfig alloc] initWithAppId:@"YOUR_WORKSPACE_ID" dataCenter: DATA_CENTER];
    
// MoEngage SDK Initialization
    // Separate initialization methods for Dev and Prod initializations
    #ifdef DEBUG
         [[MoEngage sharedInstance] initializeDefaultTestInstance:sdkConfig];
    #else
         [[MoEngage sharedInstance] initializeDefaultLiveInstance:sdkConfig];
    #endif
    
  //Rest of the implementation of method
  //-------
}
```

* In your MoEngage account, if your [portfolio](https://moengage.com/docs/user-guide/settings/account/portfolio/portfolio.md) is configured with multiple projects, Provide the respective Project ID along with the Datacenter while initializing the SDK with MoEngageSDKConfig instance . Use [initializeDefaultTestInstance(\_:)](https://moengage.github.io/ios-api-reference/Classes/MoEngage.html#/c:@M@MoEngageSDK@objc\(cs\)MoEngage\(im\)initializeDefaultTestInstance:) and[ initializeDefaultLiveInstance(\_:)](https://moengage.github.io/ios-api-reference/Classes/MoEngage.html#/c:@M@MoEngageSDK@objc\(cs\)MoEngage\(im\)initializeDefaultLiveInstance:) methods as shown below:

> [!NOTE]
>
> * **Portfolio attributes without `projectConfig`.** If you set any portfolio attribute without passing a non-empty `projectId` during SDK initialization, the SDK throws an exception, resulting in an application crash in `DEBUG` mode. If you are using portfolio attributes, you must provide the `projectConfig`.

```swift Swift wrap theme={null}
let sdkConfig = MoEngageSDKConfig(appId: "YOUR_WORKSPACE_ID", dataCenter: DATA_CENTER)
sdkConfig.projectConfig = MoEngageProjectConfig(projectId: "YOUR_PROJECT_ID")
#if DEBUG
MoEngage.sharedInstance.initializeDefaultTestInstance(sdkConfig)
#else
MoEngage.sharedInstance.initializeDefaultLiveInstance(sdkConfig)
#endif
```

```objective-c Objective C wrap theme={null}
MoEngageSDKConfig* sdkConfig = [[MoEngageSDKConfig alloc] initWithAppId:@"YOUR_WORKSPACE_ID" dataCenter: DATA_CENTER];
sdkConfig.projectConfig = [[MoEngageProjectConfig alloc] initWithProjectId:@"YOUR_PROJECT_ID"];
#ifdef DEBUG
[[MoEngage sharedInstance] initializeDefaultTestInstance:sdkConfig];
#else
[[MoEngage sharedInstance] initializeDefaultLiveInstance:sdkConfig];
#endif
```

> [!WARNING]
>
> **Validations during initialization**
>
> The MoEngage iOS SDK enforces the following checks while initializing. Each of these throws a fatal exception and crashes the app. This is to ensure no incorrect integration seeps into production.
>
> * **Empty Workspace ID.** Initializing `MoEngageSDKConfig` with an empty `appId`.
> * **SDK version downgrade.** Downgrading the MoEngage iOS SDK to a lower version than what the app was previously shipped with is not supported. The SDK detects the downgrade during initialization and crashes in `DEBUG` builds.
> * **API calls before initialization.** Calling MoEngage SDK APIs before the SDK is initialized throws a fatal exception. Initialize the SDK in `application(_:didFinishLaunchingWithOptions:)` before invoking any other MoEngage API. You can call any API after the initialize method returns

Following details of the different data centers you need to set based on the dashboard hosts

| Data Center | Dashboard host |
| :- | :- |
| MoEngageDataCenter.data\_center\_01 | dashboard-01.moengage.com |
| MoEngageDataCenter.data\_center\_02 | dashboard-02.moengage.com |
| MoEngageDataCenter.data\_center\_03 | dashboard-03.moengage.com |
| MoEngageDataCenter.data\_center\_04 | dashboard-04.moengage.com |
| MoEngageDataCenter.data\_center\_05 | dashboard-05.moengage.com |
| MoEngageDataCenter.data\_center\_06 | dashboard-06.moengage.com |

For more information about the detailed list of possible configurations, refer to the [API reference](https://moengage.github.io/ios-api-reference/Classes/MoEngageSDKConfig.html).

> [!NOTE]
>
> **Note**
>
> ***data\_center\_06*** is available from MoEngage-iOS-SDK version 9.17.3 onwards

> [!WARNING]
>
> **Important**
>
> Make sure to call the initialization method in `applicationDidFinishLaunching(_:)` method. In case if you are initializing the SDK at a later stage and not at launch then you will have to call all the notification related methods instead of just relying on [AppDelegate Swizzling](https://www.moengage.com/docs/developer-guide/ios-sdk/push/basic/ios-push-integration-tutorial#app-delegate-method-swizzling).

# Test/Live Environment

As mentioned above while initializing the build, MoEngage SDK makes use of the `DEBUG` preprocessor macro to decide whether the build is meant for TEST/LIVE Environment. Therefore, you will have to take care of the same while generating the build and make sure that the **Build Configuration** of the App's target is set as mentioned below:

* For **Development** Build: Build Configuration should be set to **Debug** (Data will be tracked in **TEST** Environment)
* For **AdHoc Build/App Store** Build: Build Configuration should be set to **Release** (Data will be tracked in **LIVE** Environment)

> [!WARNING]
>
> **What if Build Configuration is not set correctly?**
>
> If the build configuration is not set correctly following might happen:
>
> * You will see the data from the development build in LIVE environment
> * **OR** data from AdHoc/Production Build in TEST environment
> * You will get **Bad Device Token** error while trying to send a push notification to the device

# How to set Build Configuration?

## Build Configuration on Running the app from Xcode:

Whenever you run the app directly from Xcode without archiving, make sure the build configuration of **Run mode** of the App Target in Edit Scheme is set to **Debug**(set by default settings). Doing this will make sure data is tracked in TEST Environment.

![Sdkini3](https://mintcdn.com/moengage/Jtvf10ggM77HdKvB/images/sdkini3.png?fit=max\&auto=format\&n=Jtvf10ggM77HdKvB\&q=85\&s=1c3e28e9ae39412781e5504bc085d6d4)

## Build Configuration on Exporting the build:

While exporting the build make sure you set the correct `Build Configuration`. By default for Archive section in `Edit Scheme` the `Build Configuration` will be set to `Release`, but for a development build make sure its changed to `Debug` before exporting the build. To set the **Build Configuration** of the build in your Xcode project go to **App Target > Edit Scheme > Archive > Build Configuration** and set the configuration to **Debug/Release**(depending on the type of build). Refer to the image as described:

![Sdkini4](https://mintcdn.com/moengage/Jtvf10ggM77HdKvB/images/sdkini4.png?fit=max\&auto=format\&n=Jtvf10ggM77HdKvB\&q=85\&s=d1de3e92696d22d81733ab587d3f9fd3)

# Switching Environment in Dashboard

In the MoEngage dashboard you can switch between [test and live environment](https://moengage.com/docs/user-guide/getting-started/initial-setup/dashboard-overview.md#live-and-test-environments) for your app.

**TEST** Environment is used for all the development and testing-related uses and **LIVE** environment is used for running all the campaigns for AppStore Builds for your app's user base.


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