---
title: App Replacement
framework: Bundle Resources
role: symbol
role_heading: Property List Key
platforms: [iOS 27.1+, iPadOS 27.1+]
path: bundleresources/entitlements/com.apple.developer.superseded-application-identifiers
---

# App Replacement

An entitlement that allows an app to offer the ability to migrate settings and data from and replace an older app with a specified app identifier.

## Discussion

Discussion This entitlement enables you to replace apps on iOS and iPadOS using a prioritized list of app identifiers associated with your developer account. On the first launch of an app that has adopted this entitlement and provided a list of one or more app identifiers associated with your developer account, the system enumerates the identifiers in the order presented in the list. For the first enumerated identifier that matches an app someone has already installed on the device, the system gives the person the option of replacing the app with a new app that inherits the older app’s data and settings. If the person agrees to the replacement, the system deletes the older app once the data and settings migration process completes. The app replacement offer process is a first-run activity and runs only once. important: The original and the replacement app must be under the same developer membership, and they must have substantively the same primary purpose and functionality. To request access to this capability, see App Replacement Request. Adopt the entitlement To adopt this entitlement, add it to your app’s capabilities by following these steps: In the Xcode project navigator, select your app’s target, and then the Signing & Capabilities tab. Add a new capability by clicking the + Capability button and then type “App Replacement” in the search field. Double-click the App Replacement entry to add the entitlement to your app. In the Xcode project navigator, double-click your app’s Entitlements file. Select and edit the App Replacement dictionary entry and provide an array of app identifiers for past versions of the app in priority order, as shown in the following example. You can find app identifiers in the record for each app in your team’s account on the Apple Developer portal. <plist> <dict>     <key>com.apple.developer.superseded-application-identifiers</key>     <array>     <string>com.example.app-v3</string>     <string>com.example.app-v2</string>     <string>com.example.app-v1</string>     </array> </dict> </plist> You can test the app placement workflow using TestFlight.