Upload Apps for Oculus Quest

Apps that target Oculus Quest 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.

Prerequisites

Before you can upload your app, you must:

• Have an account with Oculus and set up a development organization. For more information, see Manage Your Organization and Users
• Create a page for your app in the developer dashboard. For more information, see App Submission and Store Review.
• Make sure your app and expansion files meet the size, manifest and signing requirements.
  • The APK may be up to 1 GB in size. Quest APKs smaller than 400 MB can be upload with the web interface, otherwise use the Oculus Platform command-line tool or the integrations for the Platform tool in Unity or Unreal Engine.
  • 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.

APKs and Expansions files

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.

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 (OBB) 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 4 GB, 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

Upload Quest Builds

You can upload app builds to Oculus with:

• The Oculus Developer Dashboard web interface
• The Oculus Platform Command Line Utility
• Unreal Engine, see Upload Apps to Oculus from the Unreal Editor
• Unity, Upload Apps to Oculus from the Unity Editor

Upload your build through the web interface

Use the following steps to upload your app to the Oculus Developer Dashboard. Note that apps uploaded with the web interface should be less than 200 MB in size.

1. Log on to the Oculus Developer Dashboard at https://developer.oculus.com/manage/.
2. In App Manager, select your app.
3. Select Release Channels, and choose a channel to upload to (Production, RC, Beta, Alpha) and then Upload new build. Alternatively, you can select Create Release Channel to create a custom channel, and upload to that channel. For more information, see Release Channels.
4. Click Choose File and select the .apk file of your build. Note that if you have previously uploaded a build that contains expansion files, you must use the Oculus Platform command-line utility to upload a new build.

Upload your app through the command line interface

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, and the command line utility can handle larger app packages. 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.

Apps uploaded with the utility can be up to 1 GB in size. For apps with expansion files, or larger APKs, you can upload your app with the Oculus Platform Utility. Apps uploaded with this command-line tool can be up to 1 GB in size.

• See Oculus Platform Utility for information about how to use the utility.

Upload your app from the Unity or Unreal editors

If you are using Unity with the Oculus Asset imported, or Unreal engine, you can access the Oculus Platform tool through UI in the editor. Your app packages should be less than 1 GB in size.

• For Unreal, see Upload Apps to Oculus from the Unreal Editor.

• For Unity, see Upload Apps to Oculus from the Unity Editor.

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 Quest 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. Expansion files must be uploaded with the command-line utility.

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.

• For 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 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 Quest.
  • Oculus Quest does not have a 2D phone display, and therefore some app behaviors (such as push notifications, or authentication through a separate Android application) do not make sense on it.
  • Oculus Quest does not have cameras, and cannot run applications that rely upon access to a camera.
  • Oculus Quest does not have a touchpad on the HMD. Your app should not refer to an HMD touchpad when running on Quest.

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 the Quest and Quest 2 controllers is acceptable.
• A correct application manifest. The application manifest of your Quest 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.