Building Mobile Applications
This section describes the steps necessary for building Gear VR apps in Unity.
During the build process, Unity projects with VR support enabled are packaged with an automatically-generated manifest which is configured to meet our requirements (landscape orientation, vr_only, et cetera). All other values, such as Entitlement Check settings, are not modified. Do not add the noHistory attribute to your manifest.
To build an application for submission to the Oculus Store, you must build a custom manifest using the Oculus Utilities for Unity. See Building Mobile Apps for Submission to the Oculus Store for details.
Oculus Signature File
Your application must include an Oculus Signature File or osig. See "Sign your App with an Oculus Signature File" in Preparing for Mobile Development for more information.
From the File menu, select Build Settings…. Select Android as the platform. Set Texture Compression to ASTC.
- Click the Player Settings… button and select the Android tab.
- Set a Bundle Identifier under Identification in Other Settings.
- Select Virtual Reality Supported under Rendering in Other Settings.
All required settings are enforced automatically, but you may wish to make additional settings as appropriate, such as enabling Multithreaded Rendering. For more information on our recommended settings, see the Best Practices for Rift and Gear VR section.
Navigate to Edit > Project Settings > Quality. We recommend the following settings:
Pixel Light Count
2x or 4x Multi Sampling
Realtime Reflections Probes
Bilboards Face Camera
The Anti-aliasing setting is particularly important. It must be increased to compensate for stereo rendering, which reduces the effective horizontal resolution by 50%. An anti-aliasing value of 2X is ideal, 4x may be used if you have performance to spare. We do not recommend 8x.
For more information on our recommended settings, see Best Practices for Rift and Gear VR.
Build and Run the Application
Build your application for the Android Platform and load it onto your phone. When you launch the application, you will be prompted to insert your phone into the Gear VR headset.
- Save the project before continuing. If you are not already connected to your phone via USB, connect now. Unlock the phone lock screen.
- On some Samsung models, you must set the default USB connection from Connected for charging or similar to Software installation or similar in the Samsung pulldown menu.
- From the File menu in the Unity Editor, select Build Settings…. While in the Build Settings menu, add your scenes to Scenes in Build if necessary.
- Verify that Android is selected as your Target Platform and select Build and Run. If asked, specify a name and location for the APK.
- The APK will be installed and launched on your Android device.
To run your application later, remove your phone from the Gear VR headset and launch the app from the phone desktop or Apps folder. Then insert the device into the Gear VR when prompted to do so.
Note that your will not see your application listed in your Oculus Home Library - only applications approved and published by Oculus are visible there.
Sideloading Unity Applications
You may build an APK locally and sideload it to your phone.
To do so, follow all of the instructions above, except in the final steps, select Build instead of Build and Run.
Once you have built an APK on your local system, you may copy it to your phone by following the instructions in Using adb to Install Applications in our Mobile SDK Developer Guide.
Running Mobile Apps Outside of the Gear VR Headset
When Developer Mode is enabled on your phone, Oculus applications will run without inserting the phone into the Gear VR headset. This can be convenient during development.
VR applications run in Developer Mode play with distortion and stereoscopic rendering applied, and with limited orientation tracking using the phone's sensors.
For instructions on setting your device to Developer Mode, see Developer Mode: Running Apps Outside of the Gear VR Headset in our Mobile SDK Developer Guide.
Building Mobile Apps for Submission to the Oculus Store
If you are building an application for the Oculus Store, you will need to take a few extra steps.
- Create a custom manifest using the Oculus Utilities for Unity
- Remove your osig
- Sign your application with an Android Keystore
- Enable Entitlement Checking with the Oculus Platform SDK
For more information on the submission process, see our Publishing Guide.
1. Build a Custom Manifest for Submission
To build an APK that includes a manifest with the values required by the Oculus Store, you must download the Oculus Utilities for Unity 5 package and import it into your project as described in Importing the Oculus Utilities Package.
Once you have a done so, in the Unity Editor, select Tools > Oculus > Create store-compatible AndroidManfiest.xml. Then build your project normally.
2. Remove your osig
We recommend removing your Oculus Signature File before building your application for submission.
3. Sign your application with an Android Keystore
Mobile applications must be signed with an Android signature for submission. Unity automatically signs applications with a temporary Android debug certificate by default. Before building your final release build, create a new Android keystore by following the “Sign Your App Manually” instructions in Android's Sign your Applications guide. Then assign it with the Use Existing Keystore option, found in Edit > Project Settings > Player > Publishing Options.
For more information, see the Android section of Unity's documentation.
4. Enable Entitlement Checking with the Oculus Platform SDK
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.