On Demand Resources Is Deprecated: What Background Assets Costs

Apple retired a decade-old content delivery system in 13 words: “On Demand Resources and the NSBundleResourceRequest API are deprecated. Use Background Assets instead.”¹

That sentence is the complete entry. It carries radar 170066290, sits under Deprecations, and repeats verbatim in three separate release notes.¹²³ Apple published no removal version, no migration guide keyed to the deprecation, and no companion note in the macOS or watchOS release notes.

The work hides in the last four words. Background Assets is not one thing. It forks into three configurations with different hosting models, different minimum deployment targets, and migration costs separated by roughly an order of magnitude. The choice happens before you write a line of code, and picking wrong is the expensive mistake.

TL;DR

• Apple deprecated On Demand Resources and NSBundleResourceRequest in the iOS and iPadOS 27, tvOS 27, and visionOS 27 release notes.¹²³ ODR keeps working. Apple named no removal date, and the deprecated APIs still ship and still resolve tags.
• The API’s own availability data deprecates it on six platforms, two more than any release note mentions: Mac Catalyst and watchOS.⁴ Background Assets publishes no watchOS availability at all, so watchOS receives a deprecation with no documented replacement.⁵⁶
• “Use Background Assets instead” forks three ways: managed with Apple hosting, managed with your own hosting, and unmanaged. Both managed paths require iOS 26.0 as a minimum deployment target.⁷⁸ Below 26.0 only the unmanaged path is open, and it requires you to host the files, invent the manifest format, and parse it yourself.⁹
• Disk management inverts. ODR let the system purge unused tagged resources and took setPreservationPriority(_:forTags:) as a hint about ordering.⁴¹⁰ Background Assets keeps every downloaded pack on device until your code calls remove(assetPackWithID:).¹¹
• Apple hosts up to 200 GB of compressed asset packs and up to 200 packs per app record, shared across every platform your app offers, uploaded to App Store Connect and reviewed separately from builds.¹²¹³

What Apple deprecated, precisely

Three details in the note carry weight, and the note states none of them.

Scope is wider than the release notes. Three documents carry the entry: iOS and iPadOS 27, tvOS 27, and visionOS 27, each under an On Demand Resources heading with a Deprecations subheading, each citing the same radar.¹²³ The macOS 27 and watchOS 27 notes say nothing about it.

The API’s availability annotation tells a wider story. NSBundleResourceRequest reads as introduced in iOS 9.0 and deprecated in 27.0, with the identical 27.0 deprecation on iPadOS 9.0, Mac Catalyst 13.1, tvOS 9.0, visionOS 1.0, and watchOS 2.0.⁴ Six platforms in the metadata, four named across the notes. Bundle’s two preservation-priority methods carry the same six-platform annotation.¹⁰ An audit driven by release notes alone misses the Mac Catalyst and watchOS entries entirely.

The Mac Catalyst entry is nominal. Apple documents that NSBundleResourceRequest “ignores calls from Mac apps built with Mac Catalyst,” so the deprecation retires an API that never did anything there.⁴ The watchOS entry is not nominal. Background Assets lists availability for iOS 16.0, iPadOS 16.0, Mac Catalyst 16.0, macOS 13.0, tvOS 18.4, and visionOS 2.4, with no watchOS row.⁵ Apple states plainly that Apple-hosted asset packs are “available for apps distributed through the App Store on all platforms except watchOS.”⁶ A watchOS app using ODR gets a deprecation warning and no replacement to migrate to.

Force is the weakest of the three 27-cycle changes I have covered. Deprecated means deprecated. Apple published no removal version, no submission gate, and no runtime failure. Compare the same cycle’s scene life cycle mandate, where apps built with the new SDK “fail to launch,” or the launch screen requirement, where the App Store rejects the build outright. ODR does neither. Existing tags keep resolving, existing calls keep returning resources, and shipped binaries keep working. What arrives is a compiler warning and a clock nobody can read.

Timing reads as a decision, not a cleanup. Apple deprecated the API across four platform names at once, one release after the managed tier of its replacement shipped. Treat the deprecation as the opening of a migration window whose length Apple has not published, and not as an emergency.

The fork you take before writing code

Apple’s framework overview describes two hosting models and a managed default that “handles downloads, updates, compression, and more for you.” For Apple hosting, “you upload your assets to App Store Connect and maintain them there, similar to app builds.”⁵ Xcode’s Background Download extension template names two types directly, Apple-Hosted, Managed and Self-Hosted, Unmanaged.⁹¹¹ A third combination exists in the property list keys: BAHasManagedAssetPacks set to YES without BAUsesAppleHosting selects managed asset packs that you host yourself, and its documentation routes you to the ManagedDownloaderExtension protocol rather than StoreKit’s StoreDownloaderExtension.⁷⁸¹⁴

The deployment target decides for most teams. Every managed entry point requires at least iOS 26.0, from AssetPackManager and ManagedDownloaderExtension down to the three property list keys.⁷⁸¹⁴¹⁵ An app supporting iOS 18 cannot adopt the managed tier at all, and its options narrow to the unmanaged path, which reaches back to iOS 16.1, or staying on deprecated ODR until the deployment target moves.⁹

The unmanaged path is a different job. Apple’s sequence has the system download a manifest from BAManifestURL before your app launches, hand the file to your extension, and take back a set of download requests.⁹ Apple states the division without hedging: “It’s your responsibility to create manifest files for your self-hosted, unmanaged assets (using your format of choice) that your code parses to get the URLs and file sizes to the system.”⁹ You supply hosting, a CDN, a manifest schema, a parser, and a domain allowlist. Anyone reading “use Background Assets instead” as an API swap is reading the managed tier and quoting the unmanaged bill.

What ODR gave you that you rebuild by hand

Three ODR behaviors have no drop-in equivalent.

Tags become asset packs. ODR identified content with string tags assigned in Xcode, and NSBundleResourceRequest(tags:) claimed one or more of them.⁴ Background Assets replaces tags with asset packs: directories of files described by a JSON manifest, compressed into a .aar archive by a command-line tool. The unit of granularity grows, and the assignment moves out of Xcode’s asset catalog into a file you maintain.

Apple hosting becomes a separate release train. ODR content rode along with the build. Apple-hosted asset packs upload independently through Transporter, altool, iTMSTransporter, or the App Store Connect API, and you submit them for App Review separately from the app.¹¹¹³ The decoupling is the feature: you ship new content without shipping a build. The cost is a second submission pipeline, a second review queue, and a second set of statuses to monitor.

Automatic purging becomes your job, and the inversion is the sharpest change. ODR treated downloaded content as a cache the system owned. Apple documented that the system “will not attempt to purge the resources marked with a tag from on-device storage as long as at least one NSBundleResourceRequest object is managing the tag,” which is a promise about when purging happens rather than whether.⁴ setPreservationPriority(_:forTags:) existed precisely to give “a hint to the system of the relative order for purging tagged sets of resources in the bundle.”¹⁰ You ended your claim, the system reclaimed the space on its own schedule, and low-storage handling was Apple’s problem.

Background Assets reverses the ownership. The system keeps packs updated automatically, and checkForUpdates() removes packs that went obsolete on the server.¹⁵ Neither mechanism evicts a pack you simply finished with. Apple’s instruction is explicit: “the system won’t automatically remove your asset packs while your app is installed. Therefore, when you are done with an asset pack, call the remove(assetPackWithID:) method.”¹¹

The scoped, reference-counted pattern collapses into an explicit delete you have to decide to call:

// ODR: claim a tag, use the file, release the claim.
// The system reclaims the space afterward on its own schedule.
let request = NSBundleResourceRequest(tags: ["Tutorial"])
try await request.beginAccessingResources()
let url = Bundle.main.url(forResource: "Introduction", withExtension: "m4v")
request.endAccessingResources()

import System  // url(for:) and contents(at:) take a FilePath

// Background Assets: ensure the pack, read the file, delete the pack.
// Nothing reclaims the space if you skip the last line.
let manager = AssetPackManager.shared
guard let pack = try await manager.manifest.assetPack(withID: "Tutorial") else { return }
try await manager.ensureLocalAvailability(of: pack, requireLatestVersion: false)
let url = try manager.url(for: "Videos/Introduction.m4v")
try await manager.remove(assetPackWithID: "Tutorial")

Every app carrying an ODR eviction assumption needs a storage policy written for it. The failure mode is quiet: nothing crashes, nothing warns, and device storage climbs until a user notices your app in the storage list.

The migration surface, item by item

For the Apple-hosted managed path, Apple’s own steps produce this checklist.

Group files into asset packs and pick a download policy per pack. Three policies exist. essential downloads during installation and contributes to the progress people watch in the App Store, in TestFlight, and on the Home Screen. prefetch starts during installation and continues in the background after installation finishes. onDemand downloads only when your code asks.¹¹ For essential and prefetch, a nested installationEventTypes array takes firstInstallation, subsequentUpdate, or both, so a tutorial pack can download on first install and skip every later update.¹¹

Write a manifest per pack. Xcode generates an annotated template:

xcrun ba-package template -o Manifest.json

{
  "assetPackID": "Tutorial",
  "downloadPolicy": {
    "essential": {
      "installationEventTypes": ["firstInstallation"]
    }
  },
  "fileSelectors": [
    { "file": "Videos/Introduction.m4v" },
    { "directory": "Textures/Tutorial" }
  ],
  "platforms": ["<identifiers from the generated template comments>"]
}

File paths resolve relative to the directory where you run the packaging command, which matters again later when you read files back by path.¹¹ Archive each pack:

xcrun ba-package Manifest.json -o Tutorial.aar

Add a Background Download extension target under Application Extension, choosing Apple-Hosted, Managed as the type. Add the App Groups capability to both the app and the extension, and put both in the same group. Then add three property list keys to the app target: BAAppGroupID, BAHasManagedAssetPacks set to YES, and BAUsesAppleHosting set to YES. Apple instructs you to omit every other Background Assets key for Apple-hosted projects.¹¹ One constraint is easy to trip over: adopting AssetPackManager without also adopting the matching extension protocol is, in Apple’s words, “a programmer error.”¹⁵

Reading files back works through a merged namespace. Apple “automatically merges all of your asset packs into a shared namespace, effectively reconstructing your asset root folder as if it were pasted on a person’s device,” so code addresses files by path without tracking which pack holds them.¹¹ Reads return memory-mapped Data by default, with a file-descriptor variant for procedural loading that you must close yourself.¹¹

Local testing carries a setup cost worth budgeting separately. Background Assets uses HTTPS for every download, so the mock server needs a certificate. Apple’s documented path runs through Keychain Access to create a self-signed root CA, Apple Configurator to build a profile carrying that CA, installing and trusting the profile on every test device, issuing an SSL leaf certificate whose name matches the server’s IP address or hostname exactly, starting the server, and setting a URL override in Developer settings on each device.¹⁷

xcrun ba-serve --host localhost Tutorial.aar HighQualityTextures.aar

Budget that sequence as its own task. On Demand Resources needed no server of yours at any point: Apple describes it as a manager for “content hosted on the App Store,” and resources missing from the device “are requested from the App Store.”⁴ Migrating means standing up hosting, or a trusted mock of it, before you can exercise a single download. Reading the two workflows side by side, I expect the certificate chain rather than the API adoption to consume the first day of a migration.

The numbers to plan against

Apple publishes two hard ceilings for Apple-hosted packs: 200 GB total and 200 asset packs per app record. Both are “shared across all platforms offered for your app.”¹² Apple computes the total from the maximum size across versions eligible for TestFlight or App Store distribution, excluding Awaiting Upload, Processing, Failed, and fully Superseded versions, and emails you at 80% of the limit. Archiving a pack recovers space by removing all of its versions, including versions live on the App Store.¹²

The unmanaged path replaces those ceilings with four top-level property list keys you set yourself, one of them a dictionary carrying three more, and the compressed-versus-uncompressed split is a genuine trap. BADownloadAllowance and BAEssentialDownloadAllowance bound download sizes and take compressed values. BAMaxInstallSize and BAEssentialMaxInstallSize bound installed sizes and take uncompressed values.⁹ Apple attaches a warning to the install-size keys that is really a product warning: “The App Store uses this key to show the size of your app on the product page, so provide an accurate value … Don’t overstate the disk space you require.”¹⁸ BADownloadDomainAllowList completes the set, accepting DNS-format domains with an optional leading asterisk for wildcards.⁹

One more number belongs in the plan, and it comes from availability metadata rather than prose. AssetPackManager shipped at iOS 26.0, and four of its members already carry deprecations: ensureLocalAvailability(of:) and status(ofAssetPackWithID:) at 26.4, then assetPack(withID:) and allAssetPacks at 27.0.¹⁹ Lookup, status, and the download call each moved once, across two point releases. The route Apple now points to, through the manager’s manifest property, carries a beta annotation in the 27.0 SDK, as does the batching ensureLocalAvailability(of:requireLatestVersions:).¹⁹ Apple’s own Apple-hosted walkthrough still demonstrates two of the deprecated calls.¹¹ The practical floor therefore sits above the tier’s nominal 26.0. Writing the download path shown earlier without collecting a deprecation warning means targeting 27.0, and accepting beta-annotated symbols to do it. The replacement you are being told to adopt is younger and moving faster than the API it replaces.

Who the deprecation actually catches

The affected population is narrow, and I could not find it in my own code. I searched seven shipping projects for NSBundleResourceRequest, beginAccessingResources, setPreservationPriority, any ON_DEMAND_RESOURCES build setting, knownAssetTags, and asset-catalog tag configuration. Zero hits, in all seven, on every pattern. A repository-wide sweep of every Swift, Objective-C, property list, and pbxproj file under my projects directory returned nothing for any ODR symbol, and nothing for Background Assets either.²⁰

The null result has a cause worth naming, because it generalizes. ODR exists for apps whose content dwarfs their code. My largest asset catalog belongs to Return at 66.6 MB, and every other app sits under 8 MB, with Water and Yawara under 100 KB.²⁰ At those sizes, splitting content into packs adds network failure modes, a storage policy, and a second review pipeline while saving a download nobody complains about. The apps that genuinely need Background Assets are games with level content, apps shipping large machine-learning models, and anything with per-language video, which is exactly the population Apple’s localized asset pack support in iOS 27 targets.²¹

Deployment targets sharpen the picture, and they are the number to check first in any codebase. Five of my six iOS apps already sit at iOS 26.0 or later, so the managed tier would be available to them today. Ace Citizenship still declares 17.0 and 17.5 on some of its targets, which would rule out the managed tier and leave only the unmanaged path or deprecated ODR.²⁰ Run that check before designing anything: the minimum deployment target, not the asset payload, is what decides which migration you are actually being offered.

FAQ

Does On Demand Resources stop working in iOS 27?

No. Apple marked ODR and NSBundleResourceRequest deprecated and published no removal version, no submission gate, and no runtime failure.¹ Deprecated APIs continue to function, and existing tags keep resolving. What you get is a compiler warning. The contrast with the same cycle’s other breaking changes is instructive: the scene life cycle mandate makes apps “fail to launch,” and the launch screen requirement makes the App Store reject the build. The ODR deprecation starts a clock rather than closing a door.

Which platforms does the deprecation cover?

The release notes name four platforms across three documents: iOS and iPadOS 27, tvOS 27, and visionOS 27, all citing radar 170066290.¹²³ The API’s availability metadata is broader, marking NSBundleResourceRequest and Bundle’s preservation-priority methods deprecated at 27.0 on six platforms, adding Mac Catalyst and watchOS.⁴¹⁰ Mac Catalyst is academic because Apple documents that the class ignores calls from Catalyst apps.⁴ watchOS is not academic: Background Assets publishes no watchOS availability, and Apple-hosted packs are available “on all platforms except watchOS,” so a watchOS app has a deprecated API and no documented successor.⁵⁶

Can I migrate if my app supports iOS 18?

Not to the managed tier. AssetPackManager, ManagedDownloaderExtension, BAHasManagedAssetPacks, and BAUsesAppleHosting all require iOS 26.0.⁷⁸¹⁴¹⁵ Two options remain below that floor. The unmanaged path works from iOS 16.1, and it asks you to host the assets, define your own manifest format, parse it in an extension, and declare download allowances and a domain allowlist in your property list.⁹ Otherwise, keep using deprecated ODR until your deployment target reaches 26.0, which Apple’s lack of a removal date currently permits.

What breaks quietly if I port ODR code straight across?

Storage. ODR let the system purge unused tagged content, and setPreservationPriority(_:forTags:) only hinted at ordering.⁴¹⁰ Background Assets never removes a pack you are finished with while your app stays installed, so the space is yours until you call remove(assetPackWithID:).¹¹ Code that mirrors the old beginAccessingResources and endAccessingResources pattern without adding an explicit delete leaks disk indefinitely, with no crash and no warning to catch it in testing. Write the eviction policy before you write the download code.

Key Takeaways

For iOS developers: - Check the minimum deployment target before anything else. Below iOS 26.0, the managed tier does not exist for you, and “use Background Assets instead” means building hosting, a manifest format, and a parser on the unmanaged path.⁷⁹ - Write an eviction policy as part of the migration. remove(assetPackWithID:) has no automatic counterpart, and the ODR habit of releasing a claim and trusting the system leaves storage growing silently.¹¹

For teams shipping large content: - Budget the local testing setup separately from the code. Apple’s documented path runs through a self-signed root CA, an Apple Configurator profile installed and trusted on each device, an SSL leaf certificate matching the server hostname, and a per-device URL override.¹⁷ - Plan against 200 GB and 200 packs per app record, shared across every platform your app ships on, and watch for the email Apple sends at 80%.¹² Archiving to recover space removes versions that are live on the App Store.¹²

For release managers: - Apple-hosted packs mean a second submission pipeline: uploaded through Transporter or the App Store Connect API, versioned independently of builds, and submitted to App Review on their own.¹¹¹³ Staff the review cycle accordingly. - Nothing forces the migration this cycle. Sequence ODR behind the scene life cycle mandate and the launch screen requirement, both of which carry real enforcement, and revisit when Apple publishes a removal version.

The 27 cycle keeps sorting its breaking changes by teeth: the scene life cycle stops apps from launching, the launch screen stops builds from shipping, and ODR merely starts a clock. Knowing which is which is how you spend the cycle well. For the same pattern on a smaller surface, see ImageCreator’s removal from Image Playground. The full series hub is the Apple Ecosystem Series.

References