Asset Files, DLC, and Expansion Files for Android Apps

There are two types of asset files that the Oculus platform supports for mobile apps.

• 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.
• Generic Asset files - Mobile apps can provide multiple generic asset files, which can almost any format, including OBB format. These files can be:
  • Downloadable content (DLC), downloaded at runtime and can either be free or in-app purchase (IAP) content
  • Required assets, which you configure to download at app-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.

Generic Asset Files

There are different kinds of generic asset files, either required assets or downloadable content. 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.

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.

Downloadable Content (DLC)

DLC is downloaded at runtime as a user moves through your app.

DLC:

• Can be any format, with any file extension.
• Can be up to 2 GB each.
• Can be free or made available as in-app purchases (IAP).

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. See the Commerce (IAP) page for information about defining an in-app purchase.

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.
• For DLC or an expansion file, 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" />

Game Engine Support

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:

• Unity: AssetBundles
• Unreal: Package Project

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 mobile 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 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

Example for a mobile app that contains required assets:

ovr-platform-util upload-mobile-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

Asset Config File

When you use the --asset-files-config parameter you will include a JSON file that you use to mark how assets are used:

• Associate assets (DLC) for purchase with the IAP items you have previously defined. Each SKU must resolve to a SKU you defined on the Dashboard in the previous section.
• Identify required assets, which means they are downloaded at app install time

For example:

{
    "asset1.ext": {
        "required": true
    },
    "DLC-file-name.ext": {
        "sku": "IAP-sku"
    }
}

Note: The asset_files_config replaces the asset_file_iap_config, which is limited to specifying IAP SKUs.

For more information on how to upload your mobile app with expansion or asset files, see Uploading Mobile Builds

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 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.

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 Expansion File 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/

Integrate DLC Support and Purchases in Your App Code

When a user starts your app, you should check the status of downloadable items.

1. On app startup, call ovr_AssetFile_GetList to retrieve a list of available asset files. The array returned contains an array of items. Each item contains:
   • A file name,
   • An ID
   • A status, iap_status, which is one of the following values: free, entitled, or not-entitled
   • A download status, download_status, which is one of the following values:
     • installed meaning that user has installed the file
     • available meaning that user can download the file
     • in-progress meaning the file is being downloaded or is installing for that user.
2. (Purchasable DLC Only) Use the Commerce (IAP) APIs to allow the user to complete the purchase flow. Call ovr_IAP_LaunchCheckoutFlow with the SKU you defined.
3. If there is a file that is available to download, meaning its status is free or entitled, and download_status = available, you can initiate the download by calling ovr_AssetFile_DownloadById. To make this call, pass the ID of the item as returned by the initial GetList call.
4. You’ll receive an immediate 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.