{"componentChunkName":"component---src-templates-markdown-template-jsx","path":"/developers/client-sdks/cordova/upgrade-to-version-5/","result":{"data":{"pageMetadata":{"title":"Upgrade to Version 5","path":"/developers/client-sdks/cordova/upgrade-to-version-5/","hideFromNav":null,"sourceCode":null,"metadataParent":{"title":"Cordova","path":"/developers/client-sdks/cordova/","sourceCode":"https://github.com/mParticle/cordova-plugin-mparticle","hasVersionPicker":null,"metadataChildren":[{"title":"Cordova Plugin","path":"/developers/client-sdks/cordova/getting-started/","order":1,"label":null},{"title":"Identity","path":"/developers/client-sdks/cordova/identity/","order":2,"label":null},{"title":"Upgrade to Version 5","path":"/developers/client-sdks/cordova/upgrade-to-version-5/","order":3,"label":null}],"metadataParent":{"title":"Client SDKs","path":"/developers/client-sdks/","metadataChildren":[{"title":"Alexa","path":"/developers/client-sdks/alexa/","order":1,"label":null},{"title":".NET MAUI","path":"/developers/client-sdks/maui/","order":null,"label":null},{"title":"AMP","path":"/developers/client-sdks/amp/","order":null,"label":null},{"title":"Android","path":"/developers/client-sdks/android/","order":null,"label":null},{"title":"Cordova","path":"/developers/client-sdks/cordova/","order":null,"label":null},{"title":"Direct Url Routing","path":"/developers/client-sdks/direct-url-routing/","order":null,"label":null},{"title":"Flutter","path":"/developers/client-sdks/flutter/","order":null,"label":null},{"title":"iOS","path":"/developers/client-sdks/ios/","order":null,"label":null},{"title":"React Native","path":"/developers/client-sdks/react-native/","order":null,"label":null},{"title":"Roku","path":"/developers/client-sdks/roku/","order":null,"label":null},{"title":"Unity","path":"/developers/client-sdks/unity/","order":null,"label":null},{"title":"Web","path":"/developers/client-sdks/web/","order":null,"label":null},{"title":"Xbox","path":"/developers/client-sdks/uwp/","order":null,"label":null}],"metadataParent":{"title":"Developers","path":"/developers/","metadataChildren":[{"title":"API Credential Management","path":"/developers/credential-management/","order":null,"label":null},{"title":"API References","path":"/developers/apis/","order":null,"label":null},{"title":"Client SDKs","path":"/developers/client-sdks/","order":null,"label":null},{"title":"Guides","path":"/developers/guides/","order":null,"label":null},{"title":"Media SDKs","path":"/developers/media-sdks/","order":null,"label":null},{"title":"Quickstart","path":"/developers/quickstart/","order":null,"label":null},{"title":"Server SDKs","path":"/developers/server-sdks/","order":null,"label":null},{"title":"The Developer's Guided Journey to mParticle","path":"/developers/developersjourney/","order":null,"label":null},{"title":"Tools","path":"/developers/tools/","order":null,"label":null}],"metadataParent":null}}}},"markdownRemark":{"html":"

Version 5 of the mParticle Cordova plugins (@mparticle/cordova-sdk, @mparticle/cordova-rokt-kit, and @mparticle/cordova-rokt-payment-extension) takes the native iOS SDKs from Swift Package Manager (SPM) instead of CocoaPods, because CocoaPods trunk becomes read-only on December 2, 2026. The breaking changes are on iOS. Android code is unchanged, but version 5 requires Cordova CLI 12 or later on every platform.

\n

This guide covers upgrades from 4.x. For a new integration, follow Getting Started. The plugin repository’s MIGRATING.md has the same steps.

\n

\n \n \n \n \n \n \n \n iOS

\n

The three plugins are now Swift packages. cordova-ios 8 adds them, and the native SDKs they depend on, to the Xcode project for you. The mParticle plugins don’t use CocoaPods. The native version ranges are the same as the 4.x pods:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Plugin4.x CocoaPod5.x Swift package
@mparticle/cordova-sdkmParticle-Apple-SDK ~> 9.3mparticle-apple-sdk, 9.3.0 up to 10.0.0
@mparticle/cordova-rokt-kitmParticle-Rokt ~> 9.3mp-apple-integration-rokt, 9.3.0 up to 10.0.0
@mparticle/cordova-rokt-payment-extensionRoktPaymentExtension ~> 2.0rokt-payment-extension-ios, 2.0.0 up to 3.0.0
\n

\n \n \n \n \n \n \n \n Upgrade steps

\n
    \n
  1. Move to Cordova CLI 12 or later and cordova-ios 8. cordova-ios 8 needs Node.js 20.17 or later in the 20.x line, or 22.9 or later, and Xcode 15 or later.
    2. \n
  2. \n

    In config.xml, set the deployment target to iOS 15 or later. Set it before you add the platform in step 6. cordova-ios 8.1.1 and earlier apply it to the plugins’ Swift packages only when the platform is added.

    \n
    <platform name=\"ios\">\n    <preference name=\"deployment-target\" value=\"15.0\" />\n</platform>
    \n
    3. \n
  3. \n

    Remove the iOS platform, so the plugins don’t install against cordova-ios 7:

    \n
    cordova platform rm ios
    \n
    4. \n
  4. \n

    Upgrade every mParticle plugin your app uses to 5.x together. A 4.x kit next to the 5.x core still adds its CocoaPod, which brings a second copy of the mParticle SDK into the app: it builds, then fails at runtime. Changing the spec in config.xml alone doesn’t upgrade a plugin that package.json already lists, so remove and re-add the plugins, leaving out any your app doesn’t use:

    \n
    cordova plugin rm @mparticle/cordova-rokt-payment-extension @mparticle/cordova-rokt-kit @mparticle/cordova-sdk\ncordova plugin add @mparticle/cordova-sdk@5 @mparticle/cordova-rokt-kit@5 @mparticle/cordova-rokt-payment-extension@5
    \n
    5. \n
  5. For the same reason, remove any mParticle or Rokt pods you added yourself, for example in a custom plugin’s <podspec>.
    6. \n
  6. \n

    Add the iOS platform again:

    \n
    cordova platform add ios@8
    \n

    cordova-ios 8 names the Xcode project and target App (platforms/ios/App.xcodeproj, platforms/ios/App/) instead of your app’s name. Update any hooks or scripts that find them by name.

    \n
    7. \n
  7. Move the SDK start-up into the Swift AppDelegate.swift that cordova-ios 8 generates, and import the SDK with import mParticle_Apple_SDK. See Getting Started for the code. Cordova regenerates platforms/, so keep your copy outside it and copy it in with an after_prepare hook declared in config.xml. If your 4.x hook is an after_platform_add hook, change it to after_prepare so it runs before every build.
    8. \n
  8. \n

    If you use the payment extension, delete the Swift shim (RoktPaymentSetup.swift in the 4.x example app) and any hook that copied it, created its bridging header or set SWIFT_OBJC_BRIDGING_HEADER. Keep the Bridging-Header.h that cordova-ios 8 generates. Register the extension in AppDelegate.swift, after starting the SDK. The Swift method is now registerPaymentExtension(_:):

    \n
    import RoktPaymentExtension\n\nif let paymentExtension = RoktPaymentExtension(\n    applePayMerchantId: \"merchant.com.yourapp.rokt\", // omit if not offering Apple Pay\n    urlScheme: \"myapp\" // omit if not offering Afterpay / Clearpay\n) {\n    MParticle.sharedInstance().rokt.registerPaymentExtension(paymentExtension)\n}
    \n

    If you pass urlScheme, register it under CFBundleURLSchemes in your app’s Info.plist. Otherwise the initializer returns nil, and Debug builds stop on an assertion failure.

    \n
    9. \n
  9. If you forward payment redirect URLs to Rokt in application:openURL:options:, move that code to a SceneDelegate override. cordova-ios 8 apps use scenes, so the app delegate no longer receives URLs. See Handle redirect-based payment callbacks in the plugin README.
    10. \n
  10. Build and run once. If platforms/ios has a Podfile for another plugin, it should list no mParticle or Rokt pods. With MParticle.sharedInstance().logLevel = .verbose, the log shows Included kits: {Rokt} when the Rokt kit is installed.
    11. \n
\n

\n \n \n \n \n \n \n \n Other mParticle kits

\n

cordova-ios 8 links only the Swift packages that plugins declare, so a kit pod you added another way is no longer installed. To keep using another kit, wrap the kit’s Swift package in a small local plugin, copied from the plugin repository’s Kits/Rokt:

\n
    \n
  1. Change the plugin id in plugin.xml, package.json, and Package.swift. In Package.swift, the package name and the library product name must both equal the plugin id.
    2. \n
  2. Rename the target in Package.swift, and the stub file in src/ios to match. Target names must be unique across all of the app’s packages.
    3. \n
  3. Change the package URL and product to the kit’s. The mParticle Apple SDK README lists each kit’s Swift package. Choose a kit version that supports mParticle Apple SDK 9, or Swift Package Manager cannot resolve the packages.
    4. \n
  4. The copied plugin.xml still adds the Rokt kit on Android. Remove its <platform name="android"> block, or point it at the kit’s Android artifact.
    5. \n
  5. Add the plugin to your app with cordova plugin add <path-to-plugin>.
    6. \n
\n

\n \n \n \n \n \n \n \n Capacitor

\n

Capacitor reads a Cordova plugin’s Package.swift from Capacitor 8.3.2, in apps that use Swift Package Manager. Capacitor apps that use CocoaPods get no iOS code from version 5 and should stay on 4.x. Version 5 hasn’t been tested with Capacitor.

\n

\n \n \n \n \n \n \n \n Staying on CocoaPods

\n

To stay on CocoaPods for now, keep cordova-ios 7 and pin each mParticle plugin you use at 4.x, for example cordova plugin add @mparticle/cordova-sdk@4. If package.json already saves a 5.x version, remove the plugins with cordova plugin rm first.

\n

This option is deprecated. CocoaPods trunk is scheduled to stop accepting new pods and versions on December 2, 2026. Existing published versions remain available, so 4.x stays on the last mParticle SDK released to CocoaPods.

\n

\n \n \n \n \n \n \n \n Android

\n

No code changes are required on Android. The plugins still add com.mparticle:android-core 6.0.0 and, with the Rokt kit plugin, com.mparticle:android-rokt-kit 6.0.0. Version 5 requires Cordova CLI 12 or later.

","frontmatter":{"title":"Upgrade to Version 5","order":3,"seoTitle":null,"seoDescription":null},"parent":{"__typename":"File","modifiedTime":"October 28, 2026"}}},"pageContext":{"slug":"/developers/client-sdks/cordova/upgrade-to-version-5/"}},"staticQueryHashes":["159144251"]}