class · iOS 26.0+ · SDK 27.1
actor AssetPackManagerAn actor that manages asset packs. The first time that your code refers to the shared manager, Background Assets considers that your app is opting into automatic system management of your asset packs. - Important: When using the asset-pack manager, make sure that you also adopt the corresponding managed extension protocol, ``ManagedDownloaderExtension`` (for self-hosted asset packs) or `StoreDownloaderExtension` from StoreKit (for Apple-hosted asset packs). Not doing so is a programmer error.
get allAssetPacks(): Promise<Array<AssetPack>>var allAssetPacks: Set<AssetPack> { get async throws }The asset packs that are available to download. Accessing this property may cause an attempt to get the latest asset-pack information from the server.
assetPack(id: string): Promise<AssetPack>func assetPack(withID id: String) async throws -> AssetPackReturns the asset pack with the given ID. This method may attempt to get the latest asset-pack information from the server if the system hasn’t cached that information locally. To force the system to get the latest information from the server unconditionally, call ``checkForUpdates()``. - Parameter id: The asset pack’s ID. - Returns: The asset pack. - Throws: ``ManagedBackgroundAssetsError/assetPackNotFound(withID:)`` when no asset pack with the given ID is found.
assetPackIsAvailableLocally(assetPackID: string): booleannonisolated func assetPackIsAvailableLocally(withID assetPackID: String) -> BoolChecks whether an asset pack is available locally. - Parameter assetPackID: The asset pack’s ID. - Returns: Whether the asset pack is available locally.
descriptorForSearchingInAssetPackWithID(path: _System_FilePath, assetPackID?: (string) | null): _System_FileDescriptornonisolated func descriptor(for path: FilePath, searchingInAssetPackWithID assetPackID: String? = nil) throws -> FileDescriptorOpens and returns a file descriptor for an asset file at the specified relative path. - Important: It’s your responsibility to close the file descriptor when you’re done using it. All asset packs share the same namespace, so you can treat the overall collection of downloaded asset packs as if it were a single root directory that contains all of your subdirectories and asset files, regardless of the specific asset pack in which any particular file resides. If there’s a path collision across multiple asset packs, then it’s undefined from which asset pack the file will be read unless you explicitly limit the search to a particular asset pack by passing a non-`nil` ID to the `assetPackID` parameter. - Parameters: - path: The relative path. - assetPackID: The ID of the asset pack in which to search for the file. By default, all downloaded asset packs are searched. - Returns: A descriptor for the opened file. - Throws: ``ManagedBackgroundAssetsError/fileNotFound(at:)`` when no file is found at `path`. - Throws: When the path is not relative or when some other error occurs while finding or opening the requested file. - Remark: Use this method if you need low-level access to the file descriptor. If you don’t, then use ``contents(at:searchingInAssetPackWithID:options:)`` instead.
descriptorForAsLocalizedFor(path: _System_FilePath, language: _Foundation_Locale_Language): _System_FileDescriptornonisolated func descriptor(for path: FilePath, asLocalizedFor language: Locale.Language) throws -> FileDescriptorOpens and returns a file descriptor for a localized asset file at the specified relative path. - Important: It’s your responsibility to close the file descriptor when you’re done using it. All asset packs share the same namespace, so you can treat the overall collection of downloaded asset packs as if it were a single root directory that contains all of your subdirectories and asset files, regardless of the specific asset pack in which any particular file resides. This method searches in only the downloaded asset packs that are localized in the specified language. If there’s a file-path collision across multiple such asset packs, then it’s undefined from which asset pack the file will be read. This method is most useful if you intentionally induce a file-path collision across multiple differently localized asset packs. For example, you may include an English-localized version of `Videos/Introduction.m4v` in an `en` asset pack, a Hebrew-localized version of `Videos/Introduction.m4v` in a `he` asset pack, and an American Spanish–localized version of `Videos/Introduction.m4v` in an `es-US` asset pack. If you offer split-language functionality to users, then you may want to download two or more of those asset packs on the same device. In that scenario, the specific choice of file that ``descriptor(for:searchingInAssetPackWithID:)`` opens would be undefined unless you determine the appropriate asset pack’s ID and pass it to that method’s `assetPackID` parameter. With this method, merely passing a `Locale.Language` instance to the `language` parameter is sufficient to resolve the ambiguity without requiring that you determine the asset pack’s ID. ``descriptor(for:searchingInAssetPackWithID:)`` is more suitable in most other situations. - Note: Language matching considers implicit script and region tags per Unicode’s Common Locale Data Repository. For example, `en` is equivalent to `en-US` and `en-Latn-US` but not `en-CA`. - Parameters: - path: The relative path. - language: The language that the framework uses to limit the search within localized asset packs. - Returns: A descriptor for the opened file. - Throws: ``ManagedBackgroundAssetsError/fileNotFound(at:)`` when no file is found at `path`. - Throws: When the path is not relative or when some other error occurs while finding or opening the requested file. - Remark: Use this method if you need low-level access to the file descriptor. If you don’t, then use ``contents(at:asLocalizedFor:options:)`` instead.
localStatus(assetPackID: string): Promise<AssetPack_Status>func localStatus(ofAssetPackWithID assetPackID: String) async -> AssetPack.StatusChecks an asset pack’s local status. This method checks only status values that are determinable offline. It doesn’t induce any network traffic or automatically trigger any downloads, updates, or removals. The following status values are determinable offline: - ``AssetPack/Status/outOfDate`` (in some situations) - ``AssetPack/Status/obsolete`` (in some situations) - ``AssetPack/Status/downloaded`` Because this method doesn’t communicate with the server, it can’t determine whether a particular asset pack exists in the first place. Instead, it returns an empty status value when provided a nonexistent asset-pack ID, which is indistinguishable from the situation in which the asset pack does indeed exist but hasn’t yet been downloaded. Use ``status(ofAssetPackWithID:)`` to get a full view of an asset pack’s status. - Parameter assetPackID: The asset pack’s ID. - Returns: The asset pack’s local status.
statusUpdates(assetPackID: string): (SDKHandle) & (SDKHandle)nonisolated func statusUpdates(forAssetPackWithID assetPackID: String) -> some Sendable & AsyncSequence<AssetPackManager.DownloadStatusUpdate, Never>
Returns an asynchronous sequence of download-status updates for the asset pack with the specified ID. The sequence finishes after yielding ``DownloadStatusUpdate/finished(_:)`` or ``DownloadStatusUpdate/failed(_:_:)``. - Parameter assetPackID: The asset pack’s ID. - Returns: An asynchronous sequence of download-status updates.
checkForUpdates(): Promise<{ "updatingIDs": Array<string>; "removedIDs": Array<string> }>@discardableResult func checkForUpdates() async throws -> (updatingIDs: Set<String>, removedIDs: Set<String>)Gets the latest asset-pack information from the server, updates outdated asset packs, and removes obsolete asset packs. This method waits for any downloads that it schedules to be registered with the download manager, but it doesn’t wait for those downloads to begin or to finish. If you want to monitor download progress, then you should await status updates on ``statusUpdates`` or ``statusUpdates(forAssetPackWithID:)``. - Returns: A 2-tuple with the set of IDs of asset packs that are being updated and the set of IDs of asset packs that were removed as a result of the check for updates. Neither updates nor removals that weren’t triggered by the check for updates are taken into account.
get unownedExecutor(): SDKHandlenonisolated final var unownedExecutor: UnownedSerialExecutor { get }Retrieve the executor for this actor as an optimized, unowned reference. This property must always evaluate to the same executor for a given actor instance, and holding on to the actor must keep the executor alive. This property will be implicitly accessed when work needs to be scheduled onto this actor. These accesses may be merged, eliminated, and rearranged with other work, and they may even be introduced when not strictly required. Visible side effects are therefore strongly discouraged within this property. - SeeAlso: ``SerialExecutor`` - SeeAlso: ``TaskExecutor``
get resolvedLanguage(): (_Foundation_Locale_Language) | nullnonisolated var resolvedLanguage: Locale.Language? { get set }The language that best matches current preferences and for which the system automatically makes localized asset packs available locally. The preferred languages set in Settings or System Settings inform the choice of resolved language, respecting any language that your app sets manually by setting this property. This property may be `nil` if no localized asset packs are available. You can manually set this property to `nil` to revert to the system-wide language preference. If a person using the device recently changed their preferred language, then this property’s value might be temporarily out of sync with the set of asset packs that are available locally. Setting the language doesn’t immediately download or remove any asset packs; call ``reconcilePreferredLanguages()`` to reconcile the set of downloaded asset packs with the new configuration.
set resolvedLanguage(value: (_Foundation_Locale_Language) | null)nonisolated var resolvedLanguage: Locale.Language? { get set }The language that best matches current preferences and for which the system automatically makes localized asset packs available locally. The preferred languages set in Settings or System Settings inform the choice of resolved language, respecting any language that your app sets manually by setting this property. This property may be `nil` if no localized asset packs are available. You can manually set this property to `nil` to revert to the system-wide language preference. If a person using the device recently changed their preferred language, then this property’s value might be temporarily out of sync with the set of asset packs that are available locally. Setting the language doesn’t immediately download or remove any asset packs; call ``reconcilePreferredLanguages()`` to reconcile the set of downloaded asset packs with the new configuration.
ensureLocalAvailabilityOfRequireLatestVersion(assetPack: AssetPack, shouldUpdate?: boolean): Promise<void>func ensureLocalAvailability(of assetPack: AssetPack, requireLatestVersion shouldUpdate: Bool = false) async throwsEnsures that an asset pack is available locally, performing a download if necessary. This method checks whether the asset pack is currently downloaded. If it isn’t, then the system schedules it to be downloaded and waits for the download to finish. If the method returns without throwing, the framework guarantees that the requested asset pack is now available locally. If the method throws, then the asset pack _isn’t_ guaranteed to be available locally. You can optionally monitor download progress by awaiting status updates from ``statusUpdates`` or ``statusUpdates(forAssetPackWithID:)`` in a separate task. To download multiple asset packs at the same time, use ``ensureLocalAvailability(of:requireLatestVersions:)``. - Parameters: - assetPack: The asset pack the local availability of which to ensure. - shouldUpdate: Whether to require that the latest version be available locally. When `true` is passed to this parameter, the method will wait for the update (if there indeed is one available) to be downloaded before returning. When `false` is passed, the method won’t check for updates and won’t attempt to download any. - Throws: When the system can’t ensure the asset pack’s local availability.
ensureLocalAvailabilityOfRequireLatestVersions(assetPacks: Array<AssetPack>, shouldUpdate?: boolean): Promise<void>func ensureLocalAvailability(of assetPacks: Set<AssetPack>, requireLatestVersions shouldUpdate: Bool = false) async throwsEnsures the specified asset packs are available locally, performing a batch download if necessary. This method checks whether the asset packs are currently downloaded. If any aren’t, then the system schedules them to be downloaded and waits for all of the downloads to finish. The framework guarantees that the requested asset packs are available locally after this method returns without throwing. If the method throws, then the asset packs _aren’t_ all guaranteed to be available locally, though some might be; inspect the thrown error for more details. You can optionally monitor download progress by awaiting status updates from ``statusUpdates`` or ``statusUpdates(forAssetPackWithID:)`` in a separate task. - Parameters: - assetPacks: The asset packs the local availability of which to ensure. - shouldUpdate: Whether to require that the respective latest versions be available locally. When `true` is passed to this parameter, the method will wait for the updates (if there indeed are any available) to be downloaded before returning. When `false` is passed, the method won’t check for updates and won’t attempt to download any. - Throws: When the system can’t ensure one or more asset packs’ local availability. When the thrown error is an instance of ``LocalAvailabilityError``, it provides information about asset packs for which the system successfully ensured local availability and those for which the system couldn’t ensure local availability, with an underlying error for each failure.
ensureLocalAvailabilityOf(assetPack: AssetPack): Promise<void>func ensureLocalAvailability(of assetPack: AssetPack) async throwsEnsures that the specified asset pack is available locally, performing a download if necessary. This method checks whether the asset pack is currently downloaded. If it isn’t, then the system schedules it to be downloaded and waits for the download to complete. It’s guaranteed that the requested asset pack will be available locally once this method returns without throwing. If the method throws, then the asset pack _isn’t_ guaranteed to be available locally. You can optionally monitor download progress by awaiting status updates from ``statusUpdates`` or ``statusUpdates(forAssetPackWithID:)`` in a separate task. - Parameter assetPack: The asset pack the local availability of which to ensure. - Throws: When the asset pack can’t be downloaded.
get locallyAvailableLanguages(): Promise<Array<_Foundation_Locale_Language>>var locallyAvailableLanguages: [Locale.Language] { get async }The languages used by asset packs that are localized and are available locally.
reconcilePreferredLanguages(): Promise<void>func reconcilePreferredLanguages() async throwsReconciles the set of locally available asset packs with the current preferred languages. This method downloads any missing localized asset packs, waits for those downloads to finish, and removes any unneeded ones. If you’ve overridden the preferred languages by setting ``resolvedLanguage``, then this method will respect that. It won’t remove any localized asset packs that you’ve downloaded manually. - Throws: When the set of locally available asset packs can’t be reconciled with the preferred languages. When the thrown error is an instance of ``LocalAvailabilityError``, it provides information about asset packs for which the system successfully ensured local availability and those for which the system couldn’t ensure local availability, with an underlying error for each failure.
urlFor(path: _System_FilePath): stringnonisolated func url(for path: FilePath) throws -> URLReturns a URL for the specified relative path. - Warning: Don’t persist the returned URL beyond the lifetime of the current process. - Note: This method will return a well formed URL even if no item exists at the specified relative path in any asset pack, in which case any attempts to get its contents—whether it’s a file or a directory—will fail. All asset packs share the same namespace, so you can treat the overall collection of downloaded asset packs as if it were a single root directory that contains all of your subdirectories and asset files, regardless of the specific asset pack in which any particular file resides. Unlike ``contents(at:searchingInAssetPackWithID:options:)`` and ``descriptor(for:searchingInAssetPackWithID:)``, this method supports retrieving entire directories—including packages—in which case it merges the corresponding slices of the shared logical directory from all downloaded asset packs that contain such slices. If there’s a path collision across multiple asset packs, then it’s undefined from which asset pack an individual file will be resolved. - Warning: This method is less efficient than are ``contents(at:searchingInAssetPackWithID:options:)`` and ``descriptor(for:searchingInAssetPackWithID:)``; use those methods instead if you can do so. In particular, this method shouldn’t be used to get the URL to the root of the shared asset-pack namespace. Don’t use this method to block the main thread. - Parameter path: The relative path. - Returns: The URL to the item. - Throws: When the path isn’t relative or when some other error occurs while finding the requested item.
urlForAsLocalizedFor(path: _System_FilePath, language: _Foundation_Locale_Language): stringnonisolated func url(for path: FilePath, asLocalizedFor language: Locale.Language) throws -> URLReturns a URL for the specified relative path. - Warning: Don’t persist the returned URL beyond the lifetime of the current process. - Note: This method will return a well formed URL even if no item exists at the specified relative path in any relevant asset pack, in which case any attempts to get its contents—whether it’s a file or a directory—will fail. All asset packs share the same namespace, so you can treat the overall collection of downloaded asset packs as if it were a single root directory that contains all of your subdirectories and asset files, regardless of the specific asset pack in which any particular file resides. Unlike ``contents(at:asLocalizedFor:options:)`` and ``descriptor(for:asLocalizedFor:)``, this method supports retrieving entire directories—including packages—in which case it merges the corresponding slices of the shared logical directory from all downloaded asset packs that are localized in the specified language and that contain such slices. If there’s a path collision across multiple such asset packs, then it’s undefined from which asset pack an individual file will be resolved. - Warning: This method is less efficient than are ``contents(at:asLocalizedFor:options:)`` and ``descriptor(for:asLocalizedFor:)``; use those methods instead if you can do so. In particular, this method shouldn’t be used to get the URL to the root of the shared asset-pack namespace. Don’t use this method to block the main thread. This method is most useful if you intentionally induce a file-path collision across multiple differently localized asset packs. For example, you may include an English-localized version of `Videos/Introduction.m4v` in an `en` asset pack, a Hebrew-localized version of `Videos/Introduction.m4v` in a `he` asset pack, and an American Spanish–localized version of `Videos/Introduction.m4v` in an `es-US` asset pack. If you offer split-language functionality to users, then you may want to download two or more of those asset packs on the same device. In that scenario, the specific choice of item the URL to which ``url(for:)`` returns would be undefined. With this method, merely passing a `Locale.Language` instance to the `language` parameter is sufficient to resolve the ambiguity. ``url(for:)`` is more suitable in most other situations. - Note: Language matching considers implicit script and region tags per Unicode’s Common Locale Data Repository. For example, `en` is equivalent to `en-US` and `en-Latn-US` but not `en-CA`. - Parameters: - path: The relative path. - language: The language that the framework uses to limit the search within localized asset packs. - Returns: The URL to the item. - Throws: When the path isn’t relative or when some other error occurs while finding the requested item.
remove(assetPackID: string): Promise<void>func remove(assetPackWithID assetPackID: String) async throwsRemoves the specified asset pack from the device. - Parameter assetPackID: The asset pack’s ID.
static get shared(): AssetPackManagerstatic let shared: AssetPackManagerThe shared manager.
statusOfAssetPackWithID(assetPackID: string): Promise<AssetPack_Status>func status(ofAssetPackWithID assetPackID: String) async throws -> AssetPack.StatusChecks an asset pack’s status. This method attempts to get the latest asset-pack information from the server. It doesn’t automatically trigger any downloads, updates, or removals. - Parameter assetPackID: The asset pack’s ID. - Returns: The asset pack’s status. - Throws: ``ManagedBackgroundAssetsError/assetPackNotFound(withID:)`` when no asset pack with the given ID is found.
statusRelativeTo(assetPack: AssetPack): Promise<AssetPack_Status>func status(relativeTo assetPack: AssetPack) async throws -> AssetPack.StatusChecks the current status relative to a particular asset pack. This method checks whether any version of the specified asset pack is currently downloaded. If one is, then it determines the version relationship between the downloaded asset pack and the specified asset pack. If they have different version numbers, then the returned status value will contain ``AssetPack/Status/outOfDate``. The returned status value will contain ``AssetPack/Status/updateAvailable`` only if the relevant asset pack on the server hasn’t been further updated since the initialization of the provided ``AssetPack`` instance. For example, consider the following sequence of events, assuming that version 1 of the relevant asset pack is already available locally: 1. Your app calls ``AssetPackManifest/assetPack(withID:)`` on the ``AssetPackManifest`` instance that ``manifest`` returns to obtain an ``AssetPack`` instance. 2. The asset pack is updated to version 2 on the server. 3. Your app calls this method, passing the ``AssetPack`` instance from step 1. In this case, the returned status value will indicate that the downloaded asset pack is up to date. Generally, you shouldn’t need to handle this type of situation explicitly because the system automatically polls for updates periodically in the background. This method doesn’t automatically trigger any downloads, updates, or removals. - Parameter assetPack: The asset pack. - Returns: The current status relative to the asset pack.
contentsAtSearchingInAssetPackWithIDOptions(path: _System_FilePath, assetPackID?: (string) | null, options?: _Foundation_NSData_ReadingOptions): ArrayBuffernonisolated func contents(at path: FilePath, searchingInAssetPackWithID assetPackID: String? = nil, options: Data.ReadingOptions = .mappedIfSafe) throws -> DataReturns the contents of an asset file at the specified relative path. All asset packs share the same namespace, so you can treat the overall collection of downloaded asset packs as if it were a single root directory that contains all of your subdirectories and asset files, regardless of the specific asset pack in which any particular file resides. If there’s a file-path collision across multiple asset packs, then it’s undefined from which asset pack the file will be read unless you explicitly limit the search to a particular asset pack by passing a non-`nil` ID to the `assetPackID` parameter. - Parameters: - path: The relative path. - assetPackID: The ID of the asset pack in which to search for the file. By default, all downloaded asset packs are searched. - options: Options for how to read the file’s contents into a `Data` instance. - Returns: The file’s contents. - Throws: ``ManagedBackgroundAssetsError/fileNotFound(at:)`` when no file is found at `path`. - Throws: When the path is not relative or when some other error occurs while finding or reading the requested file.
contentsAtAsLocalizedForOptions(path: _System_FilePath, language: _Foundation_Locale_Language, options?: _Foundation_NSData_ReadingOptions): ArrayBuffernonisolated func contents(at path: FilePath, asLocalizedFor language: Locale.Language, options: Data.ReadingOptions = .mappedIfSafe) throws -> DataReturns the contents of a localized asset file at the specified relative path. All asset packs share the same namespace, so you can treat the overall collection of downloaded asset packs as if it were a single root directory that contains all of your subdirectories and asset files, regardless of the specific asset pack in which any particular file resides. This method searches in only the downloaded asset packs that are localized in the specified language. If there’s a file-path collision across multiple such asset packs, then it’s undefined from which asset pack the file will be read. This method is most useful if you intentionally induce a file-path collision across multiple differently localized asset packs. For example, you may include an English-localized version of `Videos/Introduction.m4v` in an `en` asset pack, a Hebrew-localized version of `Videos/Introduction.m4v` in a `he` asset pack, and an American Spanish–localized version of `Videos/Introduction.m4v` in an `es-US` asset pack. If you offer split-language functionality to users, then you may want to download two or more of those asset packs on the same device. In that scenario, the specific choice of file that ``contents(at:searchingInAssetPackWithID:options:)`` reads would be undefined unless you determine the appropriate asset pack’s ID and pass it to that method’s `assetPackID` parameter. With this method, merely passing a `Locale.Language` instance to the `language` parameter is sufficient to resolve the ambiguity without requiring that you determine the asset pack’s ID. ``contents(at:searchingInAssetPackWithID:options:)`` is more suitable in most other situations. - Note: Language matching considers implicit script and region tags per Unicode’s Common Locale Data Repository. For example, `en` is equivalent to `en-US` and `en-Latn-US` but not `en-CA`. - Parameters: - path: The relative path. - language: The language that the framework uses to limit the search within localized asset packs. - options: Options for how to read the file’s contents into a `Data` instance. - Returns: The file’s contents. - Throws: ``ManagedBackgroundAssetsError/fileNotFound(at:)`` when no file is found at `path`. - Throws: When the path is not relative or when some other error occurs while finding or reading the requested file.
get manifest(): Promise<AssetPackManifest>var manifest: AssetPackManifest { get async throws }The manifest of asset packs that are available to download.
1 declarations were excluded from these bindings. Each reason comes from the generator or the iOS SDK compiler.
AssetPackManager.statusUpdates
The iOS SDK compiler rejected this binding: actor-isolated property 'statusUpdates' can not be referenced from a nonisolated context