There are two types of asset files that the Oculus platform supports for mobile apps.
These files are uploaded to the Oculus store when you upload your APK.
As stated previously, the OBB expansion file can be up to 4 GB in size. The OBB file is automatically downloaded and installed when a user installs your application. The file is installed on the users device into the /sdcard/Android/obb/[package name]
folder. You can give the file any name at upload time, and it will be renamed in the following format: main.[version-code].[package-name].obb
. When you app starts, you can access the file at the install location.
Downloadable content can be provided as generic asset files in any format. The user downloads this content at app runtime. You can make this content free or for purchase.
If you plan to make your DLC available for purchase, you need to define the items as in-app purchases (IAP) before you upload the files to the Oculus store. This requires you to upload a file that contains SKU, name, description, currency, price and item type for each IAP item in tab-separated format. Please see the Commerce (IAP) page for information about defining an in-app purchase. You will need to associate each dynamic asset with a IAP item in the upload process that follows.
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
Unity and Unreal offer packaging features that are compatible with the generic assets in the Oculus platform. For Unity, you package the content as AssetBundles, and for Unreal you chunk the package. For more information, see:
You must upload all expansion and asset files with your APKs to the Oculus store with the Oculus Command Line Utility (ovr-platform-util).
Use the upload-mobile-build
command to upload mobile apps. To include expansion files, use one of the following parameters.
--obb
parameter to specify the path to the OBB file--assets_dir
parameter to specify the directory that contains the assets for upload.Example for a mobile app that contains an OBB file and DLC files:
ovr-platform-util upload-mobile-build --app_id 12345 --app_secret 1234 --apk /path/to/mygame.apk --obb path/to/myGame.obb --assets-dir /path/to/myGame/assets --channel ALPHA
For more information on how to upload your mobile app with expansion or asset files, see Uploading Mobile Builds
If you are providing content for purchase, you must associate your DLC with the IAP items that you previously defined. Note that each SKU must resolve to a SKU you defined on the Dashboard in the previous section. You do this with JSON file that associates a DLC file name with an IAP sku. For example:
[{
"filename": "DLC-file-name.ext",
"sku": "IAP-sku"
}, {
"filename": "DLC-file-name.ext",
"sku": "IAP-sku"
}]
Provide the JSON in the upload command using the --asset_file_iap_configs_file
parameter and provide the path to a file containing the JSON definitions. For example:
ovr-platform-util upload-mobile-build --a 12345 -s 1234 --apk /path/to/mygame.apk --obb path/to/myGame.obb> --assets-dir /path/to/myGame/assets --channel ALPHA --asset_file_iap_configs_file [path-to-iap-config-file]
You can view all of the expansion files on the Oculus dashboard. Navigate to dashboard.oculus.com. Hover on your app and choose Manage Builds. On the Build Dashboard, find the channel, click the ellipses
and choose View Expansion Files. The Build Expansion Files page displays, which contains sections for the OBB File, Asset Files (DLC).The following image shows an example.
To manage the file, click the ellipses button under the Action column and choose Set price, Delete or Download the file.
You must upload new files with the command line utility described in the Upload expansion files section.
Access the OBB file in your app startup. You will find the file at the following location, with the following name: /sdcard/Android/obb/[package name]main.[version-code].[package-name].obb
When you test locally, the OBB file needs to be manually pushed to /sdcard/Android/obb/
after the main APK has been installed. You can use the Android Debug Bridge (ADB) tool to do this. For example:
To remove a previously installed OBB file:
adb uninstall com.oculus.demo adb shell rm /sdcard/Android/obb/main.1.com.oculus.demo.obb
Install the APK file:
adb push -p bundles.apk /data/local/tmp adb shell pm install -g /data/local/tmp/bundles.apk adb shell rm /data/local/tmp/bundles.apk
Push the new expansion file
adb push -p main.1.com.oculus.demo.obb /sdcard/Android/obb/
When a user starts your app, you should check the status of downloadable items.
iap_status
, which is one of the following values: free, entitled, or not-entitleddownload_status
, which is one of the following values: ovr_IAP_LaunchCheckoutFlow
with the SKU you defined.ovr_AssetFile_DownloadById
. To make this call, pass the ID of the item as returned by the initial GetList call.DownloadResult
response with the path to the asset as a confirmation that the request was successful. You should also listen for DownloadUpdate
notifications which return info about transferred bytes, and a complete flag that notifies you when the download is complete.