Background Assets

Discipline-enforcing skill for delivering content larger than the app bundle through the BackgroundAssets framework — Apple's system-managed channel for asset packs with charging-aware scheduling, App Store install-progress integration, and per-user quota you can't replicate with a custom URLSession stack.

When to Use

Use this skill when:

• Shipping content too large for the app bundle that isn't needed at first launch (game level packs, ML model variants, design-tool kits, media libraries)
• Shipping Foundation Models .fmadapter packs (~160 MB each, per-OS-version pinning) — Apple's docs rule out bundling
• Deciding between Apple-hosted and server-hosted asset packs
• Choosing between essential, prefetch, and onDemand download policies
• Wiring Info.plist for managed asset packs (BAHasManagedAssetPacks, BAUsesAppleHosting, BAAppGroupID)
• Handling BAErrorCode.downloadBackgroundActivityProhibited and other delivery failure modes
• Testing asset packs locally with xcrun ba-serve before uploading to App Store Connect
• Migrating off On-Demand Resources, which the 27 SDKs deprecate, or shipping localized asset packs (OS 27)
• Coordinating an app and its downloader extension that both schedule BADownloadManager downloads

Example Prompts

Real questions developers ask that this skill answers:

• "Where should I put this 500 MB game level pack?"
• "Apple-hosted or self-hosted asset packs — which should I pick?"
• "How do I ship a Foundation Models adapter?"
• "My users report the asset pack 'isn't downloading' — what should I look at?"
• "How do I test asset pack downloads without uploading to App Store Connect?"
• "How big can my asset packs be?"
• "Should I just bundle 8 GB of textures into the IPA — it's simpler?"
• "Can I use URLSession with a background configuration instead of Background Assets?"
• "I call withExclusiveControl in my app — why does my downloader extension still schedule over it?"

What This Skill Provides

• Channel decision – when Background Assets is the right tool vs. app bundle, iCloud, URLSession, or BGProcessingTask
• Apple-hosted vs server-hosted decision – cost / latency / quota / App Review tradeoffs between StoreDownloaderExtension (Apple-hosted, two-line boilerplate) and server hosting via ManagedDownloaderExtension (managed) or BADownloaderExtension (unmanaged legacy); 200 GB / 200-pack Apple-hosted quota
• Red flags – the delivery mistakes that lead to oversized IPAs, brittle download stacks, or quota surprises, including taking BADownloadManager exclusive control on only one side (the app and its extension must both use it)
• Download policy cheatsheet – essential (during install, counts toward App Store install progress), prefetch (starts during install, may continue after), onDemand (your code triggers via ensureLocalAvailability(of:)); Foundation Models adapters are always onDemand
• Info.plist setup – managed Apple-hosted minimal set (BAHasManagedAssetPacks=true + BAUsesAppleHosting=true + BAAppGroupID), managed server-hosted, and legacy unmanaged variants
• Foundation Models adapter delivery pattern – compatibleAdapterIdentifiers(name:) for variant selection, AssetPackManager.shared.statusUpdates(forAssetPackWithID:) streaming, SystemLanguageModel.Adapter.removeObsoleteAdapters() lifecycle, base-model fallback when no compatible variant is available
• Local testing – xcrun ba-package template / xcrun ba-package <manifest> for authoring; xcrun ba-serve HTTPS mock server + Developer Mode + root CA install for testing without App Store Connect uploads
• Three pressure scenarios with pushback templates – "just bundle the assets, it's simpler", "we'll just use URLSession in the background", "we'll ship one adapter for all users"
• Audit checklists – setup, lifecycle, quota/size, production-readiness; including the 80% quota warning email handler assignment

Related

• Background Assets Reference – full AssetPackManager API surface, StoreDownloaderExtension / BADownloaderExtension protocol details, Info.plist keys reference, manifest schema, xcrun ba-package / xcrun ba-serve tooling, error types, Foundation Models adapter bridge APIs
• Background Processing – BGProcessingTask / BGAppRefreshTask for compute scheduled by the system; NOT for asset delivery
• Foundation Models Adapters – the canonical consumer of Background Assets in axiom-ai; ~160 MB per pack, mandatory onDemand, per-OS variant strategy
• Foundation Models Adapters Reference – adapter runtime API consuming Background Assets