developers
Login

Expansion Files

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 up to 4 GB in size, which must be in opaque binary blob (OBB) format. Use this file to supplement your APK, which is limited to 1 GB.
  • Generic asset files - Mobile apps can provide downloadable content (DLC) as generic asset files. This DLC can be free or made available as in-app purchases (IAP). Generic asset files can be almost any format and help you manage your initial download size.

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

Generic Assets/DLC

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.

App Manifest Requirements

  • For DLC, 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:

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 DLC asset files, use the --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

Identify Assets for Purchase

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]

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

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

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

Test Expansion File Locally

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/

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.