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

# Migrate the MoEngage Capacitor SDK From CocoaPods to Swift Package Manager

> Migrate the iOS side of an existing MoEngage Capacitor application from CocoaPods to Swift Package Manager (SPM) with the Capacitor migration assistant, including the notification extensions and CI scripts.

This guide describes how to migrate the iOS side of an existing MoEngage Capacitor application from CocoaPods to Swift Package Manager (SPM). SPM support starts in `capacitor-moengage-core` [7.0.0](https://moengage.com/docs/release-notes/sdks/capacitor.md) and requires Capacitor 7. Capacitor provides a migration assistant that converts the project to SPM. The steps in this guide cover the MoEngage-specific tasks that the assistant does not handle: the MoEngage pods that your `Podfile` declares by hand, and the push notification extension targets. For the Capacitor-specific migration steps, refer to [Using Swift Package Manager](https://capacitorjs.com/docs/ios/spm) in the Capacitor documentation.

The JavaScript code, SDK initialization, and dashboard configuration remain unchanged.

## Migration Scope

> [!NOTE]
>
> The CocoaPods registry becomes read-only on December 2, 2026, and MoEngage publishes new SDK versions to CocoaPods until that date. After that date, new MoEngage SDK versions are available only through Swift Package Manager. MoEngage recommends planning the migration ahead of December 2, 2026.
>
> The migration assistant deletes the `Podfile`, `Podfile.lock`, and `App.xcworkspace`. Migrate only after every other Capacitor plugin in your application supports SPM.

## Before You Begin

* Use Capacitor 7.
* Use `capacitor-moengage-core` [7.0.0](https://moengage.com/docs/release-notes/sdks/capacitor.md) or later, and upgrade the MoEngage Geofence plugin if your application uses the Geofence plugin.
* Confirm that every other plugin in your `package.json` supports SPM. The migration assistant warns about plugins that do not.
* Identify which extension targets use MoEngage, such as a notification service extension or a content extension.
* Commit or back up the project, including the `ios` directory.

## Step 1: Upgrade the Packages

Upgrade the MoEngage plugin and the Capacitor packages, and then rebuild the web assets. The MoEngage plugin supports Capacitor 7 only, so pin the Capacitor packages to version 7. The `@latest` tag installs a later Capacitor major version, and SPM package resolution then fails.

```bash Bash theme={null}
npm install capacitor-moengage-core@^7.0.0 @capacitor/core@^7 @capacitor/ios@^7
npm install -D @capacitor/cli@^7
npm run build
```

## Step 2: Note the Manually Declared MoEngage Pods

Before you run the assistant, open `ios/App/Podfile` and note every `MoEngage-iOS-SDK` pod that the `Podfile` declares for the extension targets.

```ruby Podfile theme={null}
target 'NotificationService' do
  pod 'MoEngage-iOS-SDK/RichNotification'
end
```

The assistant deletes the `Podfile`, so the pods declared in the `Podfile` are removed with the file. You add the equivalent Swift package in [Step 5](#step-5-update-the-push-notification-extensions). The `capacitor-moengage-core` plugin adds the MoEngage iOS SDK to the main app target automatically, so pods for the main app target need no replacement.

## Step 3: Run the Migration Assistant

From the project root, run the following command:

```bash Bash theme={null}
npx cap spm-migration-assistant
```

The assistant runs `pod deintegrate`, deletes the `Podfile`, `Podfile.lock`, and `App.xcworkspace`, creates the `CapApp-SPM` folder with a `Package.swift` generated from your plugins, and adds a `debug.xcconfig` file to the `ios` directory.

> [!WARNING]
>
> If the MoEngage SDK is added through both CocoaPods and SPM, the build fails with duplicate symbols. To avoid this after the migration:
>
> * Do not recreate the `Podfile`.
> * Do not run `pod install`. It recreates the CocoaPods files.

## Step 4: Configure Xcode

1. Open the project in Xcode:

   ```bash Bash theme={null}
   npx cap open ios
   ```

2. Select the **App** project and open the **Package Dependencies** tab.

3. Click **+**, select **Add Local**, choose the `CapApp-SPM` folder, and click **Add Package**. Click **Add Package** again when the next screen appears.

4. Open the **Info** tab of the **App** project, select **Add Configuration file**, choose `debug.xcconfig`, and set its configuration to **xcconfig**.

5. Under the main app target's **General > Frameworks, Libraries, and Embedded Content**, confirm that `CapApp-SPM` is present. If `CapApp-SPM` isn't listed, click **+** and add the package.

## Step 5: Update the Push Notification Extensions

Complete this step only if your application has a notification service extension or a notification content extension that uses MoEngage.

The extension targets aren't part of `CapApp-SPM`, so add the `MoEngageRichNotification` library manually:

1. Open the [Capacitor release notes](https://moengage.com/docs/release-notes/sdks/capacitor.md), find your `capacitor-moengage-core` version, and note the **MoEngage-iOS-SDK** version listed under **Dependencies > iOS**.
2. Select **File > Add Package Dependencies**, enter `https://github.com/moengage/apple-sdk.git`, and set **Dependency Rule** to **Exact Version** with the version from the release notes.
3. On the product screen, set **MoEngageRichNotification** to the **App** target, and leave the other products set to **None**.
4. In your notification service extension target, open **General > Frameworks and Libraries**, click **+**, and add **MoEngageRichNotification**. Do the same for your content extension target if you use push templates.

> [!NOTE]
>
> When you upgrade `capacitor-moengage-core` in the future, open the Capacitor release notes, find the version you're upgrading to, and note the MoEngage-iOS-SDK version listed for it. Then, in Xcode, open **Package Dependencies**, select **apple-sdk**, and change its **Exact Version** to that version. If the `apple-sdk` version doesn't match the MoEngage-iOS-SDK version, package resolution fails.

The extension code does not change. For the notification extension setup, refer to [Rich Push](https://moengage.com/docs/developer-guide/ios-sdk/push/basic/ios-push-integration-tutorial.md) and [Push Templates](https://moengage.com/docs/developer-guide/ios-sdk/push/optional/push-templates.md) in the iOS SDK documentation.

## Step 6: Update Your Workflow

* After you add or remove an npm package, run `npx cap sync`. Capacitor updates `CapApp-SPM` for you. Do not edit the contents of `CapApp-SPM` manually, because the Capacitor CLI can overwrite manual changes.
* In CI and local scripts, remove every `pod install` step. Because the migration deletes `App.xcworkspace`, build the `.xcodeproj` instead.

## Step 7: Verify the Migration

1. In Xcode, select **Product > Clean Build Folder**.

2. Build and run the application:

   ```bash Bash theme={null}
   npx cap run ios
   ```

3. Confirm that the SDK initialization logs report the MoEngage SDK version that you upgraded to.

4. Select **Product > Archive** and confirm that the archive succeeds. The archive build tests the extension targets in a release build.

5. Send a test push notification. Confirm that the device receives the notification, that the SDK tracks the notification impression (the Notification Received event), and that rich content renders. If the application uses the Geofence plugin, verify geofence functionality as well.

## Troubleshooting

| Issue | Cause and fix |
| :- | :- |
| The migration assistant warns about a plugin | The plugin does not support SPM. Check for an updated version of the plugin, or keep the application on CocoaPods until the plugin supports SPM. |
| Duplicate symbols, or "Multiple commands produce" | MoEngage comes from both CocoaPods and SPM. A `Podfile` was recreated or `pod install` was run. Delete the `Podfile`, `Podfile.lock`, and `Pods/` folder, and rebuild. |
| Package resolution fails with a version conflict on `apple-sdk` | The `apple-sdk` version doesn't match the MoEngage-iOS-SDK version that your `capacitor-moengage-core` version uses. This mismatch usually occurs after a plugin upgrade. Open the [Capacitor release notes](https://moengage.com/docs/release-notes/sdks/capacitor.md), find your `capacitor-moengage-core` version, and note the MoEngage-iOS-SDK version listed for it. Then, in Xcode, open **Package Dependencies**, select **apple-sdk**, and set its **Exact Version** to that version. |
| Rich media does not render, or the app crashes on a rich push in a DEBUG build | `MoEngageRichNotification` is missing from the extension target or from the App target. Add the library to both targets, as described in [Step 5](#step-5-update-the-push-notification-extensions). |
| Package not found, or the build fails after you add a plugin | Run `npx cap sync ios`, and then select **File > Packages > Reset Package Caches** in Xcode. |
| Build settings from `debug.xcconfig` are missing | The configuration file is not attached. Complete the configuration file step in [Step 4](#step-4-configure-xcode). |
| `MoEngageRichNotification` isn't listed when you click **+** in an extension target | The `apple-sdk` package hasn't been added to the project. Add the `apple-sdk` package with the exact version from the Capacitor release notes, as described in [Step 5](#step-5-update-the-push-notification-extensions). |
| No such module `Capacitor` or `CapacitorMoengageCore` | The App target doesn't link `CapApp-SPM`. Complete the last part of [Step 4](#step-4-configure-xcode): confirm that `CapApp-SPM` is listed under **Frameworks, Libraries, and Embedded Content**, and add `CapApp-SPM` with **+** if the package isn't listed. |
| Notifications arrive, but images and templates don't show | `MoEngageRichNotification` isn't linked to the App target. Select the **App** target, open **General > Frameworks, Libraries, and Embedded Content**, click **+**, add **MoEngageRichNotification**, and rebuild. |


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