Preparing for Mobile Development

To prepare for Unity mobile development for Gear VR, you must set up the Unity Editor for Android development and install the Android SDK. The Oculus Mobile SDK is not required.

We recommend reviewing Unity’s Getting started with Android development for general information on Android development, but the essential setup steps are described below.

Once you have set up the Unity Editor for Android development, VR support is enabled by checking the Virtual Reality Supported checkbox in Player Settings. Applications targeting the Android Platform will then run on Gear VR.

Unity automatically applies orientation tracking, stereoscopic rendering, and distortion correction to your main camera when VR support is enabled. For more details, see Unity VR Support.

If you are already prepared for Unity Android development, you are nearly ready to begin developing for Gear VR.

Mobile Device Setup

Follow the instructions in the Device Setup section of our Mobile SDK Developer Guide to prepare to run, debug, and test your Gear VR applications.

Android SDK

The Android SDK is required for mobile development with Unity. For setup instructions, see Standalone Android SDK Tool (Windows) or Standalone Android SDK Tool (OS X) in our Mobile SDK Developer Guide. Most Unity developers do not need to install Android Studio or NDK.

Once you have installed the Standalone Android SDK tools, you may continue with this guide.

Once you have installed the Android SDK, you may wish to familiarize yourself with adb (Android Debug Bridge), a useful tool used for communicating with your Android phone. For more information, see Adb in our Mobile Developer Guide.

Sign your App with an Oculus Signature File

All Gear VR applications must be signed with an Oculus Signature File (osig) during development to access low-level VR functionality on your mobile device. This signature comes in the form of an Oculus-issued file that you include in your application.

Each signature file is associated with a specific mobile device, so you will need an osig file for each device that you use for development.

Please see our osig self-service portal for more information and instructions on how to request an osig for development:

Once you have downloaded an osig, be sure to keep a copy in a convenient location for reuse. You will only need one osig per device for any number of applications.

Make a copy of the osig and copy it to the following directory:

If that directory does not exist, create it and copy the osig file to it. Note that the folder names are caps sensitive and must be exactly as stated above.

If you attempt to run a Gear VR APK that has not been correctly signed with an osig, you will get the error message “thread priority security exception make sure the apk is signed”.

We recommend removing your osig before building a final APK for submission to the Oculus Store. When your application is approved, Oculus will modify the APK so that it can be used on all devices. See Building Mobile Apps for Submission to the Oculus Store for more information.

Application Entitlement Checking

Entitlement checking is used to protect apps from unauthorized distribution. It is disabled by default in Unity. Entitlement checking is not required for development, but it is required for submitting an application to the Oculus Store.

For more information and instructions, see Getting Started with the SDK in our Platform guide.

Getting Started with Mobile Development

Mobile applications are subject to more stringent limitations and requirements and computational limitations than Rift applications.

We strongly recommend carefully reviewing Mobile Development and Best Practices for Rift and Gear VR in our Developer Guide to be sure you understand our performance targets and recommendations for mobile development. These sections contain important information that can help you avoid mistakes that we see frequently.

Previewing Gear VR apps in Rift

You may find it useful to preview mobile applications using the Oculus Rift during development, but use caution when doing so. The rendering path for Android applications differs substantially from the rendering path used for Rift application previews and builds, and you may notice important differences in the look-and-feel and performance.

Designing Apps for Both Rift and Mobile

When developing for both Rift and mobile platforms, keep in mind that their requirements differ substantially. If you would like to generate builds for both PC and mobile from a single project, it is important to follow the more stringent mobile development best practices, as well as meeting the required 90 FPS required by the Rift. This approach is not often taken in practice.

Additional Sources of Information

For information on Oculus tools to assist with mobile development, such as our Sample Framework or the Oculus Remote Monitor for performance debugging, please see Other Oculus Resources for Unity Developers.

For information on core VR development concepts, see the Intro to VR in our PC Developer Guide. It is written from the perspective of Rift development, but many contents apply equally well to mobile design.

Most Unity developers do not need to install the Oculus Mobile SDK. However, advanced developers may find it useful to review our Mobile SDK Developer Guide for insight into the underlying logic. Developers interested in the Android lifecycle and rendering path of Oculus mobile applications should review our documentation on VrApi. Mobile Best Practices and General Recommendations may also be of interest.

If you are interested in submitting an application to the Oculus Store, please see our Publishing Guide. We recommend doing so before beginning development in earnest so you have a realistic sense of our guidelines and requirements.