After combing the forums and release nodes, here are some extra notes to help other developers using Apple-Hosted Background Assets. I don't promise I got this perfect, but it may help direct you.
AssetPack.Status is an OptionSet (not an enum!) - Critical API detail missing from guide
- It's a bitmask where values can be combined
- 2⁰ (1) = available to download
- 2¹ (2) = update available
- 2² (4) = up to date
- 2⁶ (64) = downloaded
- Example: status value 69 = 0b1000101 = available + up to date + downloaded
- Use .contains() method to check specific flags
AssetPack.version property - Undocumented feature
- Auto-assigned by App Store Connect for Apple-hosted packs
- Increments with each upload of same asset pack ID
No file deduplication across asset packs
- Same file in two packs = counts twice toward 200GB limit
- Best practice: create separate pack for shared files
Shared namespace path requirements
- Asset pack ID is NOT part of file path
- Each file must have unique relative path across ALL app's asset packs
- Example: Foo/10/239/414.png and Bar/10/239/414.png are distinct and won't collide
Additional url(for:) bugs beyond iOS 26.1 fix
- iOS 26 Beta 5: "item with same name already exists" error
- Workaround: Request URL for directory, then manually append filename
TestFlight-only availability - Major limitation not mentioned!
- Apple-hosted packs currently ONLY work for internal testers on TestFlight or from App Store.
- Won't work from Xcode until "later this year"
- HTTP 400 errors expected for non-TestFlight installs
ba-serve port workaround
- URL override port bug exists on multiple device types
- Use ba-serve -p 443 instead of custom ports