feat!: Swift Package Manager by default on iOS; placeholder names only in selectPlacements

[thomson-t]

Why

React Native apps on iOS get the mParticle SDKs from CocoaPods, whose central repository becomes read-only on 2 December 2026, so no new versions can be published there after that date (CocoaPods announcement). Once this lands and is released, iOS apps take the mParticle SDKs from Swift Package Manager by default. The same release removes the old way of pointing embedded placements at a view, which depends on React Native internals that are being removed, so partners take one breaking upgrade instead of two. Partners who cannot upgrade yet can stay on 3.x, which is planned to get fixes from a maintenance branch.

Programme

This is the last step of the plan to move this SDK's iOS dependencies to Swift Package Manager before the CocoaPods deadline. The series was reviewed and merged pull request by pull request into a shared release branch, and this pull request brings that branch into main so it ships as the next major release. The plan and the release announcement are internal and cannot be linked here.

What changes

Before: iOS apps get the mParticle SDKs from CocoaPods, kits are declared as pods, and selectPlacements accepts either an array of placeholder names or a map of name to findNodeHandle tag.

After, on iOS:

• Swift Package Manager is the default. React Native and this SDK still install with CocoaPods, but pod install links the mParticle core SDK and each kit into the app target as Swift packages, pinned to exact versions. No Podfile call is needed (feat(ios): add opt-in Swift Package Manager mode for the mParticle SDKs #423, feat(ios)!: take the mParticle SDKs from Swift Package Manager by default #429).
• Kits by name: $RNMParticleSPMKits = ['mParticle-Rokt']. Every kit of the mParticle Apple SDK is mapped. pod install stops, naming both fixes, if a pod would add a second copy of the SDK (feat(ios)!: take the mParticle SDKs from Swift Package Manager by default #429).
• Deprecated opt-out: $RNMParticleDisableSPM = true, or iosDependencyManager: 'cocoapods' in the Expo config plugin. A tvOS target that uses the SDK must use it, and pod install says so (feat(ios)!: take the mParticle SDKs from Swift Package Manager by default #429).
• Expo: the config plugin sets this up during expo prebuild and maps iosKits to packages (feat(plugin): add iosDependencyManager 'spm' to the Expo config plugin #424, feat(ios)!: take the mParticle SDKs from Swift Package Manager by default #429).
• Experimental: a Package.swift for React Native 0.87's own Swift Package Manager mode (feat(ios): add experimental Package.swift for React Native SPM mode #426).
• Debug builds show an error if the SDK is loaded twice (feat(ios): warn in debug builds when two mParticle SDK copies are loaded #421). The SDK headers are imported through one private header (refactor(ios): resolve mParticle and RoktContracts headers through one private header #422), and the Rokt-typed code moved to Swift (refactor(ios): move RoktContracts-typed code into a Swift layer #425).
• Fixes a crash in Debug builds on the New Architecture when a RoktLayoutView mounts (refactor(ios): move RoktContracts-typed code into a Swift layer #425), and lets New Architecture tvOS apps on the opt-out compile (feat(ios)!: take the mParticle SDKs from Swift Package Manager by default #429).

After, on both platforms:

• Breaking: selectPlacements accepts only an array of placeholder names, such as ['Location1']. TypeScript rejects the old map; at runtime the SDK logs an error and requests the placement without embedded views (feat(rokt)!: accept only placeholder names in selectPlacements #428).

CI gains a second iOS sample job that builds with Swift Package Manager, a check that each SDK is in the archive once, and a tvOS check; the existing "iOS Sample App" job keeps its name and now covers the CocoaPods opt-out. The README and MIGRATING guide describe the default, the kit settings, the opt-out, troubleshooting and the placeholder migration. The changelog is generated when the release is drafted.

Each change was reviewed in its own pull request. Review here is about the integration: start with the two breaking changes and the release steps under Rollout.

Linked work

Depends on: cutting the maintenance/3.x branch from main before this merges, so 3.x keeps a release line (planned, not done).
Unblocks: the next major release, drafted with a major version bump after this merges.
Related: the merged series #421, #422, #423, #424, #425, #426, #428 and #429; name-based placeholders, released in 3.4.0 (#410); releases from maintenance branches (#420).

Rollout

Path: merging puts these changes on main but publishes nothing. The next major release is published later by the release workflow with a major bump, and is live for every app that upgrades. Before merging, cut maintenance/3.x from main, which also carries the unreleased Android fix for Android Gradle Plugin 9 (#430) to 3.x. The repository merges by squash, so the changelog would show this pull request as one entry; edit the changelog in the release pull request, or allow a merge commit for this one pull request.
Feature flags: none. Apps opt out of Swift Package Manager with $RNMParticleDisableSPM = true, or iosDependencyManager: 'cocoapods' with Expo.
Turning it off: before the release is published, reverting this pull request on main takes minutes. After publishing, a version cannot be recalled; apps stay on 3.x or use the opt-out, and a fix ships in the next release.
What we watch: this repository's issues, daily for two weeks after the release, for [mParticle] errors from pod install, the duplicate-SDK error, unknown kits and embedded placements that stop appearing. A build failure the docs don't explain means a patch release; two weeks without one means it has settled.

Risks

• pod install now edits the app's Xcode project to add the Swift packages, and apps must commit that change; the README says so, and running it again changes nothing; we would see questions about unexpected project changes.
• Apps that declare mParticle kit pods fail pod install after upgrading; intended, and the error names both fixes, with steps in MIGRATING; we would see that error in partner reports.
• Apps that still pass the name-to-tag map lose their embedded placements; TypeScript rejects it at build time, the SDK logs an error, and 3.4.0 accepts names so partners can migrate first; we would see reports of missing embedded placements.
• tvOS apps must use the deprecated opt-out; pod install stops with instructions, and a React Native tvOS app built for the tvOS simulator with it; we would see tvOS reports in this repository's issues.
• The pod install hooks override private CocoaPods methods; tested with CocoaPods 1.15.2, which CI uses, and 1.16.2, and named in the README; we would see the hooks fail in CI or in reports after a CocoaPods upgrade.
• Merging before maintenance/3.x is cut would leave 3.x without a release line; not prevented by tooling, so it is the first item under Depends on; we would see no maintenance/3.x branch when this merges.
• Builds on Expo's hosted service were not run; not addressed, because they run the same expo prebuild and pod install that passed locally; we would see build failures reported from Expo's build service.

Risk class: higher — this changes how every iOS app on the release gets the SDK and removes a public API form.

Who

Written by: an automated coding agent (Claude Code), at an engineer's request, following the internal migration plan.
Code reviewed before opening: each of the eight pull requests was reviewed in its own pull request, by an independent review agent before each commit, by automated reviewers, and by an engineer; this pull request adds no new code.
Design reviewed before opening: engineers reviewed the design in the internal release announcement; the record cannot be linked.
Decision this implements: the engineering decisions of 29 September 2026, to ship Swift Package Manager and the placeholder change together in one major release with 3.x on a maintenance branch, and of 30 September 2026, to make Swift Package Manager the default; the records are internal and cannot be linked.
Checked: on 8 October 2026, this branch's content matched the last version of #429 that passed all CI checks; a clean checkout passed the JavaScript tests (39), lint, the TypeScript build and the plugin build; the published package contents include the new iOS files; the branch merges into main without conflicts. Each pull request in the series was also checked on its own, as its description records.
Not checked: CI on this pull request, which runs when it opens; builds on Expo's hosted service; tvOS at runtime; physical devices.

Size

Hand-written: about 2,000 lines added and 650 removed in 42 files; about 640 of the added lines are tests and about 180 are docs.
Generated: 2 files.
Why one pull request: it brings eight pull requests that were each reviewed and merged on their own into main together, so they ship in one major release.

Notes for reviewers

Generated files: the Xcode project files sample/ios/MParticleSample.xcodeproj/project.pbxproj and ios/RNMParticle.xcodeproj/project.pbxproj, written by Xcode. ios/mparticle_spm_kits.json (138 lines) is counted as hand-written: it was built from the mParticle Apple SDK's kit list and then edited by hand.

The branch head cec4396 has the same tree (1587e3d) as the final head of #429, e1adb91. main has two dependency bumps since the branch point, for the Android Rokt kit; they do not conflict.

🤖 Generated with Claude Code