Google Play Asset Delivery (Google PAD) is the Google Play Store's solution for delivering asset packs to applications once they are installed on a device. This solution is intended for use alongside the Android App Bundle distribution format. Whereas the App Bundle distributes a customized .apk to the end user, handling code and binaries for the initial installation, the Play Asset Delivery system provides models, textures, sounds, shaders, and other large asset files separately from the .apk. This makes it possible for apps distributed through Google Play to manage the space taken up by content by delivering content as it is needed.
Unreal Engine 4.25 and newer includes Google PAD integration through a plugin, making this system simple to implement in your own projects. This plugin provides a function library with function calls for managing downloads and requesting information from the Play Asset Delivery system. UGooglePADFunctionLibrary
is available in both C++ and Blueprint.
For additional information on shipping with Android App Bundles, see the page on Packaging for Android .
Enabling the Google PAD Plugin
The Google PAD plugin can be found in the Unreal Editor's Plugins window, under the Android section. If you enable the plugin here, the Google PAD module will load on startup, and its libraries will be available for you to use in your project.
API Reference
The following sections detail the available functions in the Google PAD function library and their usage.
Requests and Error Handling
All requests in the Google PAD function library return an EGooglePADErrorCode
denoting whether or not the operation succeeded and, if not, what specific error prevented the request from being completed. The possible error codes are as follows:
EGooglePADErrorCode |
Description |
---|---|
|
No error with the request. Proceed with the requested information as normal. |
|
The requesting app is unavailable. |
|
The requested asset pack is not available for your app's current version. |
|
The request is invalid. |
|
The requested download has not been found. |
|
The Asset Pack API is not available. |
|
Unable to obtain details about an Asset Pack due to a timeout or other network error. |
|
The download is not permitted due to current device circumstances, usually because the user is not signed into a Google account. |
|
An asset pack download failed due to insufficient storage. |
|
The Play Store app is either not installed on this device or not the official version. |
|
Returned if |
|
An unknown error occurred in downloading an asset pack. |
|
|
|
There was an error initializing the Asset Pack API. |
In addition to this return value, request functions will have an out variable providing the requested information. If you get a result of AssetPack_NO_ERROR
, you can proceed with the provided information normally. Otherwise, you should use flow control to react to the provided error code appropriately.
Getting the Location of Downloaded Files
The function GetAssetPackLocation
fetches the location of an asset pack that has been downloaded and caches information about it locally. If the asset is available, it will output an integer handle that can be used to access the cached information as needed.
Calling GetAssetsPath
and providing the location handle will output a string with the asset path for the desired asset pack. GetStorageMethod
will output an EGooglePADStorageMethod
stating the way the asset pack is stored on the user's device. Once you know the asset path and storage method, you can then use appropriate calls to access the assets.
The possible storage methods are as follows:
EGooglePADStorageMethod |
Description |
---|---|
|
The Asset Pack is unpacked into a folder containing individual asset files. These assets can be accessed via standard file APIs. |
|
The asset pack is installed as an APK containing packed asset files. These assets can be accessed via the AssetManager. |
|
No information is available about the asset pack, most likely due to an error. |
|
The asset pack is not installed, and is therefore unavailable. |
Once you are done using the above information, you must pass the location handle to ReleaseAssetPackLocation
to free the cached location info.
If GetAssetPackLocation
returns an error code for AsetPack_UNAVAILABLE
or AssetPack_DOWNLOAD_NOT_FOUND
, then the desired asset pack is unavailable and must be downloaded.
Requesting Information about Asset Packs
The function RequestInfo takes in a TArray
of asset pack names and returns an EGooglePADErrorCode
denoting their current status. RequestInfo is not required to initiate a download, but can be used to determine whether remote asset packs are valid.
Requesting or Cancelling a Download
The function RequestDownload
takes in a TArray
of strings representing the names of the asset packs you would like to download, then sends a request to the remote service to begin downloading those asset packs. If RequestDownload
shows no errors, the asset packs will be downloaded and transferred to the app asynchronously in the background.
Because this functionality is asynchronous, the RequestDownload
function does not return information about the downloaded asset pack, other than an error code denoting whether the request was successful. You must use the functions detailed in the Monitoring Download Status
section below to check for the download's current status, and to access the asset pack itself you must use GetAssetPackLocation
once the download is complete.
The function CancelDownload
also uses a list of asset pack names, and will cancel downloading the designated asset packs.
Getting Cellular Data Status
The function ShowCellularDataConfirmation
will prompt the user for whether they want to download data using their cellular network. If the prompt is already present, you can use GetShowCellularDataConfirmationStatus to return an EGooglePADCellularDataConfirmStatus
stating whether or not the user has approved the download.
Results of AssetPack_CONFIRM_UNKNOWN
and AssetPack_CONFIRM_PENDING
mean the user has not given approval yet, and the application should stand by until approval is given.
A result of AssetPack_CONFIRM_USER_CANCELLED
means that the user has chosen not to allow the use of cellular data, and downloads should not be permitted at this time.
A result of AssetPack_CONFIRM_USER_APPROVED
means that the user has given express approval to use cellular data and downloads should be allowed to proceed. Additionally, If this function returns an EGooglePADErrorCode
with a result of AssetPack_NETWORK_UNRESTRICTED
, the user is on their wi-fi network and does not need to use cellular data, therefore downloads should be permitted without the need to continue checking this function.
Monitoring Download Status
GetDownloadState
will locally cache the download status of an asset pack and return a download handle providing access to the cached information. This function takes in the name of the asset pack that you want to download and outputs the handle as an integer. You should keep the download handle cached so that you can continue to monitor the download, otherwise, you will need to re-acquire it.
With a valid download handle, you can call GetDownloadStatus
to return the status of the desired asset pack as an EGooglePADDownloadStatus
. This enum represents the status of a download as one of several possible states, which are as follows:
EGooglePADDownloadStatus |
Description |
---|---|
|
Nothing is currently known about the asset pack. |
|
An async request to download the asset pack has been made and is currently pending. |
|
The asset pack download is currently in-progress. |
|
The asset pack is being transferred to the app. |
|
Download and transfer are both complete, and the assets are now available to the app. |
|
The request to download the asset pack has failed. |
|
The request to download the asset pack has been cancelled. |
|
The asset pack download is waiting for wi-fi bandwidth to proceed. |
|
The asset pack is not currently installed. |
|
A request for information about the asset pack has failed. |
|
An async request to remove the asset pack has been made and is currently pending. |
|
An async request to remove the asset pack has failed. |
You can also use the download state handle to call GetBytesDownloaded
, which will return the number of bytes currently downloaded to the user's device, and GetTotalBytesToDownload
, which will return the total target size of the download.
Once you have finished using the download status information, you must call ReleaseDownloadState
and provide the handle to release the cached download information from memory.
Removing Asset Packs
The function RequestRemoval
takes in an asset pack name and removes the specified asset pack from the user's device asynchronously. The asset pack's removal status can be monitored with GetDownloadStatus
as above.
Recommended Implementation
Implementation of the Google PAD API can be modeled as a cycle of different states for each download.
State |
Description |
---|---|
Accessing Asset Pack |
|
Initiating Download |
|
Checking for Cellular Data Confirmation |
|
Monitoring Download Status |
|
Implementing your solution in a custom GameState class will enable you to track a download continuously even as you change scenes and game modes. Alternatively, you may want to implement your solution in a front-end game mode that loads on startup so that you can perform necessary patches and updates before starting the game. The exact details of your solution will depend on your project's specific needs for updating assets.