Uploading Android Apps

Oculus Android apps have a stringent set of packaging requirements and any app you upload must be packaged accordingly. The upload validator rejects apps that do not meet these requirements.

APK Requirements

All Android apps must be packaged as APK files and meet the following specifications:

• The APK may be up to 1GB in size.
• The APK must have an application manifest fit for a release build. See Application Manifests for Release Builds.
• The APK must be signed with an Android certificate. For more information, see Application Signing.

Reduce Download Size

You should break large apps into an APK and an expansion file(s) to improve both the developer and the user experience. For developers:

• Apps split into an APK and expansion and asset files take less time to upload.
• Expansion and asset files are hosted and served from Oculus servers.

For users:

• It takes less time to download and apply patch updates.

APK Expansion File Requirements

You can supplement your APK file with one expansion file and one or more generic asset files. Generic asset files can be identified as DLC or as required files, which means they will downloaded at app install time. If you are familiar with Google Play APK expansion files, you should know that Oculus APK expansion file sizes and naming patterns are different. Also, all apps that have expansion and asset files must be uploaded with the Oculus Platform Command Line Utility.

The legacy APK expansion file must meet the following specifications:

• The expansion file must be in the Opaque Binary Blob (OBB) file format
• Each mobile app is allowed one OBB expansion file up to 4 GB in size.
• To identify the OBB expansion file, the filename of the APK expansion must be main.versionCode.packageName.obb
  • versionCode - the version code of the APK you are uploading with the expansion file. For Unity developers, this is the Bundle Version Code in Player Settings.
  • packageName - the package name of the APK. For example: If you are uploading APK version 3 and your package name is com.oculus.example, your expansion file name should be main.3.com.oculus.example.obb
• You must use the -obb parameter of command line tool when you upload the app to provide the path to this expansion file

Required assets have the following guidance

• Required asset files should also be less that 4GB, but can be any format (including OBB format) and have any name.
• You must use the --assets_dir parameter of the command line tool when you upload the app to provide the directory that contains the additional expansion files. For more information about required asset files, see Asset Files for Mobile Apps.
• If files are required, you must use the --asset-files-config parameter, and include a JSON config file that either:
  • Marks the asset as required

Uploading Android Builds

You can upload builds through the Oculus Developer Dashboard web interface or using the Oculus Platform Command Line Utility. The Oculus Platform Command Line Utility uses delta-patching techniques to upload only the portions of your app that have changed, so generally this is faster. If there are any packaging problems with your app, the upload validation routines inform you after uploading your build so that you can correct the issue and try again. For example, you must always update the APK version when you upload a new APK for an existing app. Some apps may not support all Gear VR devices, please see the Managing Supported Devices page for information about managing the devices your app supports. This can be configured anytime after you upload your app.

Prerequisites: Before you can upload an app, you must first create an app page for it in the Oculus Developer Dashboard. For more information, see App Submission and Store Review.

To upload your build through the web interface:

1. Log on to the Oculus Developer Dashboard at https://dashboard.oculus.com.
2. Hover over your app and then click Manage Build
3. If this is the first upload for this app, click Upload Build.
4. If this is not the first upload for this app, click the ellipses (...) in the release channel you want to upload to and then select Upload New Binary.
5. Click Choose File and select the .apk file of your build.

To upload your app through the command line interface:

• See the Oculus Platform Command Line Utility topic for information about using the utility.

Change to a Previous Build

If users experience a problem with a build, or you need to roll back a build for some reason, you must upload a new build. The Select Build functionality does not work to select an older build for Android apps. This newly uploaded package can contain an APK you previously uploaded, but you must roll forward the version number for the upload tool to accept it.

Expansion Files and APKs Must Be Updated Together

Expansion files (.obbs) and APKs must be updated together. This means that even if your update contains changes only to the APK or only to the expansion file you must increment the version code for each and upload new versions of them together. The only exception is if you decide to stop providing an expansion file and decide to distribute a single APK. In this scenario, you would upload a new APK but omit the ‘–obb’ parameter.

APKs for Multiple Device Types

You can build a single APK that runs on different devices, but there are a few things to be aware of.

1. For Go/Gear, make sure you select the devices your app supports. For more information, see Managing Supported Devices.

2. For Go/Quest, make sure you use Oculus-supported features only. Your app will be scanned at upload for the following features that are not supported on Go or Quest. If these features are found, you will be required to update your app:

   • You cannot rely on Google Play Services (e.g. Google Firebase, Google Cloud Messaging, etc), or third-party libraries that depend on Google Play Services (e.g. OneSignal) when running on Oculus Go or Quest.
   • Oculus Go and Quest do not have 2D phone displays, and therefore some app behaviors (such as push notifications, or authentication via a separate Android application) do not make sense on them.
   • Oculus Go and Quest do not have cameras, and cannot run applications that rely upon access to a camera.
   • Oculus Go and Quest do not have a touchpad on the HMD. Your app should not refer to an HMD touchpad when running on them.

Additionally, your apps are checked for the following:

• Proper controller support. Controllers are different depending on the device type. If your app displays a visible controller, you should change the model displayed depending on what device you are running on. Alternatively, a stylized controller model that is distinct from both the Oculus Go or Quest Controller and the Gear VR Controller is acceptable.
• A recent SDK. Some very old Gear VR apps are still running on pre-1.0 releases of the Mobile SDK. These apps are not supported on Oculus Go or Oculus Quest.
• A correct application manifest. The application manifest of your Android app must conform to our specifications if you want to upload the app to the Oculus Store. For more information, see Application Manifests for Release Builds.
• A correctly signed APK. Different devices require different signing schemes. For more information, see Application Signing.