探索 Apple 托管的 Background Assets

Hello, I'm Gabriel. I’m a software engineer on the App Store team. And my name is Jenny. I’m an engineer on the App Processing team. Today, we’re introducing a new way to distribute assets for your app on the App Store with Background Assets. I’ll cover how your app and assets work together on people’s devices. And I will share how you can use Apple hosting for your assets.

In this session, we will first review the current available asset delivery technologies, including Background Assets. Then dive into what’s new this year, including new Swift and Objective-C APIs to manage your Background Assets, as well as Apple hosting.

We will show you how to integrate the new features into your app for iOS, iPadOS, macOS, tvOS, and visionOS, and how to do local testing.

If you would like that Apple host and deliver your assets, we will walk you through how to prepare for beta testing and App Store distribution.

Now, let’s hear from Gabriel for a recap and what’s new in Background Assets.

Thanks, Jenny. When people download an app from the App Store, they expect to use it immediately. They may leave or even delete your app if they must wait for other downloads to finish after opening it.

With Background Assets, we’re making it even easier to deliver a great first launch experience. You can configure how the system downloads your assets on devices and update them without needing to update your main app. For example, you could deliver a tutorial level only to people who newly download a game to get them playing quickly while the rest of the game is downloaded in the background, offer optional downloadable content, also known as DLC, that you unlock with In-App Purchase, or update on device machine learning models with an accelerated submission process to the App Store. Suppose that you’re developing a game with several different levels, including a tutorial. You have four options for delivering the assets for each level: Keeping everything in your main app bundle, URLSession, On-Demand Resources, or Background Assets. There are pros and cons to some of them, so let me go through it.

Keeping everything in your main app bundle forces people to wait for all of the assets to download, even if you only need some of them to start the tutorial level. You could also hit the 4GB size limit on most platforms, and updating just one of your assets would require re-uploading and resubmitting your entire app. On-Demand Resources would let people jump into the tutorial more quickly, because it lets you download some parts of your app bundle separately from TestFlight or the App Store, but you would still need to update your entire app just to update a few asset files. On-Demand Resources is a legacy technology, and it will be deprecated.

Its successor is Background Assets, with which you host your app’s assets on your own server. You can update those assets at any time without updating your whole app. At the core of Background Assets is the downloader extension, which lets you write code to schedule asset downloads before people open your app. This is great when you need full control over download behavior and post-processing. For many of you, though, we know that what matters most is that your app’s assets simply be available and up to date. With the new Managed Background Assets features, the system automatically manages downloads, updates, compression, and more for your asset packs.

In fact, we’ve written a system-provided download or extension that you can drop into your app with no custom code needed.

Plus, with the new Apple-Hosted Background Assets service for apps on TestFlight and the App Store, you no longer need to host your assets on your own server with the Apple hosting option. You get 200GB of Apple hosting capacity included in your Apple Developer Program membership.

If you’re still using On-Demand Resources, then we suggest that you start your migration to Background Assets.

With Managed Background Assets, you create multiple asset packs that each group together some of your asset files, such as the textures, sound effects, and GPU shaders for a tutorial level in a game. The system automatically downloads an asset pack on people’s devices based on its download policy. There are three download policies: Essential, Prefetch, and On-demand.

An essential download policy means that the system automatically downloads the asset pack and integrates the download into the installation process. The asset pack contributes to the overall download progress that people see in the App Store, in TestFlight, and on the home screen. And once the installation finishes and a person opens your app, the asset pack is ready to use.

A prefetch download policy means that the system starts downloading the asset pack during the installation of the app, but the download could continue in the background after the app’s installation finishes. An on-demand download policy means that the system downloads the asset pack only when you explicitly call an API method to request it.

You can either host your asset packs yourself or let Apple host them for you. Now, I’ll hand it over to Jenny to cover how Apple servers deliver asset packs and app builds. Sure thing! Each Apple hosted asset pack can be used on one app, across multiple platforms of your choice.

For the device to download the app binary and any asset pack it uses, you will first need to separately upload both to App Store Connect. You can then submit them for review for external testing in TestFlight and App Store distribution.

Once uploaded, the asset pack is assigned a version, and it is not tied to any specific app build. How the app and asset pack match up on the device is determined by the state of the asset pack version. Let me explain with some examples.

Let’s say you have three different versions for the same asset pack. Version 1 is live on the App Store, Version 2 is live for external beta on TestFlight, and Version 3 is live for internal beta on TestFlight. Only one version of the asset pack can be live for each context.

At the same time, you have some app builds on devices that are downloaded from the App Store, or through TestFlight external beta or internal beta.

The server will select to deliver the live version of your asset pack for all your app builds in that particular context.

That means app version 1.0 build 1 that is downloaded from the App Store will use asset pack version 1.

App version 2.0 build 1 that is available for external beta in TestFlight will use asset pack version 2. And app version 2.0 builds 2 and 3 in internal beta will use asset pack version 3.

Now, it is important to understand the behavior when you make updates to the Asset Pack version.

For example, if you’re happy with asset pack version 2, you can submit it for App Store distribution. It will replace the old version to be live on the App Store.

This means all versions of your app downloaded from the App Store will automatically be switched over to using asset pack version 2, including older versions that are still installed on people's devices. So, before you update the asset pack, make sure that it will work on older app builds and versions as well. Now, let’s look at an example for app build update. Let’s say you want to submit app version 2.0 build 3 for external beta testing. After approval, if the build is downloaded through external beta, it will use the older asset pack version 2. If you would like it to be paired with the newer asset pack version 3, make sure to submit the asset pack version as well. Now that you’re familiar with the concept of asset packs, Gabriel will walk you through how to create them and use them in your app. Thanks, Jenny. Now, let me show you how to use Managed Background Assets in your app.

To get started with Managed Background Assets, you’ll create asset packs, adopt the new APIs, and test your app and asset packs locally.

Let me explain how to create an asset pack.

You can use the new packaging tool for macOS, Linux, and Windows that takes files from your source repository and packages them into a compressed archive for delivery to TestFlight and the App Store. The packaging tool ships with Xcode on macOS and will soon be available to download from the download section of the Apple developer website for Linux and Windows. Let me show you the tool in action.

You can start by running the template command to generate a manifest template. On macOS, install Xcode and run xcrun ba-package template in Terminal. On Linux or Windows, make the tool available in your shell’s search path and run ba-package template.

The packaging tool will generate a manifest template. The manifest is a JSON file that you fill out to tell Apple about your asset pack. You can choose a custom ID. This is what you’ll use to identify the asset pack in your app’s code, a download policy, and the set of platforms that the asset pack supports.

Firstly, let's fill in the file selectors. A file selector selects a set of files in your source repository to include in your asset pack. There are two types of file selectors: ones that select individual files, and ones that select entire directories.

Let’s add a file selector for the game’s introductory cutscene video, using a relative path from the root of the source repository.

This asset pack’s ID is Tutorial because it contains the asset files for the game’s Tutorial level. Now, let's configure the download policy. Since the tutorial is the first thing that people experience, let’s make the tutorial asset pack available locally before someone can open the game for the first time. So, this is a great situation in which to use an essential download policy.

This tutorial level is relevant only for people who newly install the game. People who already play the game and are simply updating to a new version shouldn’t need to download the tutorial again.

So let’s restrict the essential download policy to just the first installation and exclude subsequent updates. This means that only someone who downloads the game on their device for the first time will get the tutorial’s assets.

Now that the manifest is filled out, let’s run the packaging tool again to generate a compressed archive. We’ll set the current directory to the root of the repository and pass in the path to the manifest and the path at which to save the archive. Now that the asset pack is packaged, let’s see how we can use it in the game.

With just a few lines of code, you can use the new APIs in Background Assets to read the files in your asset packs. We’ll start by adding a downloader extension in Xcode. The downloader extension is how your app schedules asset packs to be downloaded when the main app isn’t running, such as during the installation process.

Let’s add a new target and select the Background Download template.

Here you can choose whether you want to use Apple hosting or your own.

The template generates Swift code, but you can easily replace it with Objective-C code if you prefer.

Newly this year, the system now provides a fully-featured downloader extension that supports automatic downloads, background updates,and more, which you can drop into your app with no custom code. The snippet that Xcode generates with the Background Download template is already configured to use the system implementation by default. There's no other extension code to write.

In fact, you can even remove the stub shouldDownload(_:) method entirely if you don’t need to customize the download behavior. This means that you can now add a downloader extension to your app with just a few lines Xcode generated code.

If you do want to customize the download behavior, then you can provide a custom implementation for shouldDownload(_:). The system calls your shouldDownload(_:) implementation for every new asset pack that, based on the asset pack’s download policy, it plans to download in the background, and you can return a Boolean value to decide whether to proceed with the download. This can be useful if some of your asset packs have specific compatibility requirements. Now that you’ve implemented the downloader extension, let’s see how to use files inside downloaded asset packs in your main app.

The first step is to call the ensureLocalAvailability(of:) method on the shared AssetPackManager. This method checks whether the asset pack is currently downloaded. If it isn’t, then it starts downloading it and waits for the download to finish.

In most cases, the downloader extension will have already downloaded the asset pack, so the method will return quickly. In the rare situation in which the asset pack must be newly downloaded, it’s a good idea to provide visible progress information to people using your app.

In Swift, you can await status updates on the asynchronous sequence that the statusUpdates(forAssetPackWithID:) method returns.

In Objective-C, you can create an object that conforms to the BAManagedAssetPackDownloadDelegate protocol and attach it to the shared asset pack manager’s delegate property.

If you need to cancel a download, then you can do so by calling cancel() on any of the progress structures that you receive in the download status updates. Once ensureLocalAvailability(of:) returns without throwing in error, the requested asset pack is ready to use locally.

To read a file from it, call the contents(at:searchingInAssetPackWithID:options:) method on the shared asset pack manager. The first parameter is a relative path from the root of your source repository, that is, the directory from which you previously ran the packaging tool to create the asset pack, to the file that you want to read. The system automatically merges all of your asset packs into a shared namespace, effectively reconstructing your source repository as if it were copy-pasted from your development machine into people’s devices. This means that you don’t need to worry about keeping track of which asset pack contains a particular file when you want to read that file at runtime. By default, contents(at:searchingInAssetPackWithID:options:) returns a memory mapped data instance, which is suitable even for large asset files that take up a lot of space in memory.

If you need low-level access to the file descriptor, such as for reading a file into memory procedurally, then you can use the descriptor(for:searchingInAssetPackWithID:) method instead, in which case it’s your responsibility to close the descriptor when you’re done using it. You can also restrict the search to a particular asset pack by providing a non-nil argument for the assetPackID parameter of either method.

The system tracks which asset packs your app has downloaded and automatically keeps them up to date in the background. It won’t, however, automatically remove your asset packs while your app remains installed, so it’s a good practice to call the remove(assetPackWithID:) method on the shared asset pack manager to free up storage space when you don’t expect to use a particular asset pack anymore. For example, you could remove the Tutorial asset pack when someone finishes playing the tutorial level.

You can always call ensureLocalAvailability(of:) to re-download the asset pack again should, for example, someone reset their progress in the game and start playing the tutorial again.

Keep in mind that people can see the storage space that your downloaded asset packs take up listed for your app in the storage view in the Settings app on their device.

The next step is to add both your main app and your downloader extension to the same app group. The system uses the app group to facilitate coordination between your main app and your extension.

Then add the BAAppGroupID key to your main app’s Info.plist with your app group ID as string value.

Also, add the BAHasManagedAssetPacks key with true or yes as its Boolean value.

If you’re using Apple hosting, then add the BAUsesAppleHosting key with true or yes as its Boolean value. If you’re not using Apple hosting, then refer to the related documentation in the Resources section for this session to learn more about the other required Info.plist keys, including BAManifestURL. Now that the app and the extension are configured, it's time to test.

We created a new Background Assets mock server for macOS, Linux, and Windows to test asset pack downloads before you submit your app to TestFlight or the App Store. Like the packaging tool, the mock server ships with Xcode on macOS and will soon be available to download from the Downloads section of the Apple Developer website for Linux and Windows.

Background Assets uses HTTPS for all downloads, so you first need to issue an SSL certificate. To do that, you’ll create a root certificate authority. Then you’ll install that certificate authority on your test devices. After that, you'll use the certificate authority to issue an SSL certificate, and finally, you’ll start the mock server and point it to that SSL certificate. For more details, refer to the related documentation in the Resources section for this session. Once you’ve issued your SSL certificate, you can run ba-serve to start the mock server, pass in the respective paths to the Asset Pack archives that you want to serve, and set the host to which to bind.

The host can be an IP address, a host name, or a domain name. On macOS, the tool will prompt you to choose an identity, that is, a pair of a certificate and a private key from your keychain. On Linux or Windows, you’ll need to pass in the certificate and its private key on the command line. Pass the help flag to learn about additional options, including an option to set a custom port number, and coming soon on macOS, the ability to skip the identity prompt. On iOS, iPadOS and visionOS test devices, and coming soon on tvOS test devices, go to Development Overrides in Developer Settings to enter your mock server’s base URL, including its host and port. On macOS test devices, run xcrun ba-serve url-override to enter the same information.

When you build and run your app from Xcode, it’ll download its asset packs from your mock server. Now, I’ll hand it back to Jenny to talk about beta testing and distributing your asset packs. - Jenny? - Thanks Gabriel. Now that you have the new app binary and asset packs ready, let me take you through how to prepare them for beta testing on TestFlight and distribution on the App Store.

If you’re using Apple hosting, you will upload both your app binary and asset packs to App Store Connect separately, optionally test with TestFlight, and finally distribute on the App Store.

Let’s take a deeper look at how this process works for asset packs. There are several ways to upload an asset pack.

For a drag and drop UI experience, you can use the Transporter app for macOS.

For full control and transparency, you can use the App Store Connect REST APIs to build your own automation.

For a simplified command line interface, the cross platform iTMSTransporter provides useful commands and makes requests for you to the App Store Connect APIs. You can check out the documentation for all of these tools. Here, I will walk you through using Transporter and the App Store Connect API. With the Transporter app, simply drag and drop your Tutorial.aar archive into the Transporter window.

Add it to the app of your choice, then click Deliver. It will become a new version of the Tutorial asset pack.

You will be able to see the state of your asset pack upload right in the Transporter app.

If you would like full visibility of the upload process, you can use the App Store Connect API. You will need to follow three steps: create asset pack record, create version record for the asset pack, then upload the archive to the asset pack version.

First, to create the asset pack record, you can make a POST request to the backgroundAssets resource.

In the request body, put in the name of the asset pack as the assetPackIdentifier and add your app’s Apple ID in the relationships section. The response of this call will return a UUID to your asset pack, which you can use in later API calls.

Then you will create a new version for your asset pack by making a POST request to the backgroundAssetVersions resource.

In the relationships section, use the ID of the asset pack provided to you by the previous API response. This operation automatically increases the version number based on existing versions. Here we will have version 1. You will also get an ID in the response to uniquely identify version 1 of the Tutorial asset pack.

When the asset pack version is successfully created, you can use the backgroundAssetUploadFiles resource to make an upload reservation for your Tutorial.aar archive file. This step is to other upload operations like App Store screenshots.

Here you would need the asset type, file name, file size, and MD5 checksum.

Also include the relationship to the background asset version ID. The response of this call includes an ID for your upload file, and details about the upload instructions.

When you successfully upload your archive, make a PATCH call to the backgroundAssetUploadFiles with your Upload File ID, and your asset pack will start processing.

To view the asset pack’s progress, you can always get the most comprehensive information about your available asset packs in App Store Connect or using the App Store Connect APIs.

On App Store Connect, you can find the asset pack processing status under the TestFlight tab. Once the upload is successfully processed, the status will become Ready for Internal Testing. This means your new version is ready to be used in your app builds that are live for internal testing in TestFlight. You will receive an email informing that your new asset pack version is ready. You can also set up a webhook to get this notification.

Feel free to check out the WWDC25 session “Automate your development process with the App Store Connect API” to find out more about the webhook features this year.

However, during processing, if there is an issue discovered with your asset pack archive file, the version state will become Failed and you will be notified as well. You can fix the issue accordingly, and upload the asset pack again as a new version.

Using App Store Connect APIs, there are many resources you can make GET requests to, to see a list of all asset packs for your app, versions for each asset pack, and their respective states. You can follow the progress of your upload with the backgroundAssetVersions resource.

When your asset pack is processed, an Internal Beta Releases resource will be created. It will show you that the asset pack version is READY_FOR_TESTING.

After you successfully upload both your app binary and asset pack, you can start beta testing in TestFlight.

On App Store Connect, you can see that currently Tutorial version 1 is ready for internal testing. If you’d like to test your app build and asset pack version with a wider audience, you can separately submit them for external testing.

To submit an asset pack, click on the specific version and select Submit for External Testing. When the version is approved, it will see the state change to Ready for External Testing and you will receive a notification.

With App Store Connect APIs, you can also submit the asset pack version using the betaBackgroundAssetReviewSubmissions resource.

You can follow the state of the review with the external beta releases resource. It will show you when the asset pack version is ready for external testing.

After testing, when you’re ready to make your asset pack version available on the App Store, you can submit it to App Review for App Store distribution.

You can head to the distribution tab on App Store Connect and view asset packs. Now, you can submit one asset pack version by itself or alongside other asset packs, an app version, and perhaps other review items together. If you submit an asset pack version and an app version together, the App Review team will use your selected asset pack version to review your app.

To add an asset pack for review, click on Select Asset Pack, choose the version, and add for review.

When the submission is approved, you will see that the asset pack version is Ready for Distribution.

Using the App Store Connect API, you can also submit for review using the reviewSubmissions resource.

During the review, you can see the review states on the App Store releases resource. When it reaches ready for distribution, that means the people using your app will be able to download the new assets from the App Store.

Wow, we covered quite a lot of topics today. We talked about asset packs, how to create one and use it in your app, and how to upload and submit for Apple hosting.

We hope that you find this session helpful to get started with the new Managed Background Assets.

Now it's your turn. Try using the packaging tool to create your first asset pack. Then, if your app still uses On-Demand Resources, evaluate how you can migrate to Background Assets. Take a look at the documentation and adopt the new Background Assets APIs in your app. Finally, we want your feedback. Please let us know what works for you and what doesn’t using Feedback Assistant.

You can also check out everything else that’s new this year in App Store Connect by watching the “What’s new in App Store Connect” session. Plus, learn more about existing Background Assets features, including some helpful tips for local testing, with the “What’s new in Background Assets” session from WWDC23.

- Thanks for joining us. - And we look forward to your feedback.