Asset Files to Manage Download Size

Note: You are viewing the Unity version of this topic. To view this topic for native development, see Asset Files to Manage Download Size (Native). To view this topic for Unreal development, see Asset Files to Manage Download Size (Unreal).

There are two types of asset files that the Oculus platform supports for mobile apps to help you reduce the download size of your APK.

• OBB expansion files - Mobile apps can have one expansion file that must be in opaque binary blob (OBB) format, up to 4 GB in size. This file automatically downloads at install time.
• Required Asset files - Mobile apps can provide multiple generic asset files, which can almost any format, including OBB format. You mark them as required assets so they are downloaded at install time.

These files are uploaded to the Oculus store when you upload your APK.

OBB Expansion File

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 your app starts, you can access the file at the install location.

Required Assets

Required assets are downloaded at app install time.

Required Assets:

• Can be any format, with any file extension (including additional OBB files).
• Can be up to 4 GB each, although a max size of 2 GB is recommended.
• Require a config file during the app upload process that marks the item as required.

These files are not renamed by the system, and similar to the OBB file, generic assets files install on the device to the /sdcard/Android/obb/[package-name] folder.

App Manifest Requirements

• For assets, Mark your app as requiring an Internet connection. The user must be able to download the files from Oculus. To mark the app, on the App Specifications page, select Internet connection required for downloadable contents for the Is an Internet Connection Required option.
• Make sure the Android manifest file has the READ_EXTERNAL_STORAGE permission because asset files are typically stored on external storage. The following example shows the manifest entry.

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

Unity Support

Unity offers a packaging feature called AssetBundles that is compatible with the generic assets in the Oculus platform. For more information, see:

• Unity: AssetBundles

Upload Expansion and Generic Asset Files

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 Go apps or upload-quest-build to upload Quest apps. To include expansion files, use one of the following parameters.

• For an expansion OBB file, use the --obb parameter to specify the path to the OBB file
• For required or DLC asset files, use the --assets_dir parameter to specify the directory that contains the assets for upload.
• For DLC that are also available for purchase, or for required assets, use the --asset_files_config parameter to specify a path to the config file.

Example for a mobile app that contains an obb file and required assets:

ovr-platform-util upload-mobile-build -a 12345 -s 1234 -d path/to/mygame.zip --obb path/to/myGame.obb --assets_dir /path/to/myGame/assets --asset_files_config /path/to-config-file.json -c ALPHA

Asset Config File

When you use the --asset-files-config parameter you will include a JSON file identifies required assets:

For example:

{
    "asset1.ext": {
        "required": true
}

For more information on how to upload your Android app with expansion or asset files, see Uploading Android Apps

View and Manage Asset Files

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). Yes in the Required column indicates the file downloads at app installation time.

The following image shows an example.

To manage the file, click the ellipses button under the Action column.

You must upload new files with the command line utility described in the Upload expansion files section.

Integrate Expansion File Support in Your App Code

You should access the OBB file in your app startup code. You will find the file in your device’s OBB directory, which can be retrieved with the Android Context.GetObbDir function.

The file is named with the following pattern:

/[obb-directory]/[package-name]/main.[version-code].[package-name].obb

Test Files Locally

When you test locally, files that are required at app install time need to be manually pushed to the OBB directory 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 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/

You can provide asset files for your Rift apps to help reduce the download size of your app package.

• Generic Asset Files, which can be content downloaded at runtime, or required assets, downloaded at install time.

If you want to provide in-app purchases and and downloadable content for your apps, see Add-Ons - Downloadable Content and In-App Purchases.

Required Assets

Required assets are downloaded at app install time.

Required Assets:

• Can be any format, with any file extension, including language packs.
• Can be up to 4 GB each, although a max size of 2 GB is recommended.
• Require a config file during the app upload process that marks the item as required.

Unity Support

Unity offers a packaging feature called AssetBundles that is compatible with the generic assets in the Oculus platform. For more information, see:

• Unity: AssetBundles

Upload a Binary with Asset Files to the Oculus Store

To upload a binary with assets or language packs, you must use the Oculus Platform Command Line Utility. with the upload-rift-build command. To upload asset files, use one of the following parameters.

• For required files --assets_dir parameter to specify the directory that contains the assets for upload and the ` --asset_files_config` parameter and include a path to the JSON configuration file that specifies the required items.

  For example:

  $ ovr-platform-util upload-rift-build -a 12345 -s 1234 -d path/to/mygame.zip --assets_dir /path/to/myGame/assets --asset_files_config /path/to/config-file.json -c ALPHA

  The JSON configuration file contains entries to associate your DLC with the IAP items that you previously defined, or identify an item as required. Note that each SKU must resolve to a SKU you defined on the Dashboard in the previous section.

  For example:

   {
    "asset1.ext": {
        "required": true
    }
   }
  

View Assets on the Dashboard

Once you successfully upload your items, you can view and manage them on the developer dashboard. Navigate to https://dashboard.oculus.com/. On the left menu, select Manage Builds, and select your app. Then find the Expansion Files column for the build you just uploaded and then select View Expansion Files. The different kinds of assets will display.

• For Asset Files (DLCs), *Yes** in the Required column indicates the file downloads at app installation time.

The following image shows an example.