How to distribute a Gear VR app outside of the Oculus Store

If you created an app for the Samsung Gear VR and want to distribute it to testers or partners without having to go through the Oculus Store, this guide will explain exactly how to do that! But why do you need a guide for this? Can’t you just send them your APK file like you do when distributing a Cardboard app for Android? Unfortunately, the answer is no. Samsung made things a bit harder than that, so let me explain how it works.

Device IDs

To prevent apps from being widely distributed outside of the Oculus Store, Samsung requires Gear VR apps to be specifically build for a certain device. They identify a device using a so called Device ID (yes, a very creative name). This Device ID, which is NOT the same as your phone’s serial number or IMEI, is used to create an Oculus Signature File, or osig. If, and only if, you include the signature file of your specific device in your APK will you be able to install your app on your device, and your device only, unless you add multiple signatures.

Here’s how this process works:

  1. Install the Osig ID app on your Samsung device and open it to find out your Device ID
  2. Now go to the Oculus Signature File Generator page, fill in your Device ID, and click Download File to receive your osig file
  3. Add this osig file to your app project (!! Do not rename the osig file or it will not work !!)
    1. If you built your app using Headjack, go to Settings > App Signing, fill in a title, select Samsung Gear VR  as platform and Local as channel. Now click the big green + Upload Oculus Signature button and select your osig file, then click Save to upload it to your Headjack account.
    2. If you built your app using Unity, copy the osig file to the Assets/Plugins/Android/assets folder of your project, or create this folder first if it does not yet exist

You can now build your Android app as an APK and it will have your signature file in there, allowing you to install it on your Samsung device. In Headjack you do this on the Apps > *Your App* page by selecting Local as Distribution Channel and Gear VR as Platform under the Build section, then click Select signing credentials to select the osig you just uploaded, after which you can click Build application to start the build process of your app.

Installing your app

To install your Gear VR APK on your Samsung device, follow these steps:

  1. Go to Settings > Security on your Android device and enable Unknowns sources
  2. Connect your device to your computer through USB and select File Transfer (MTP)
  3. Copy your APK file to your Android device (on OSX you need Android File Transfer)
  4. Download a file explorer app, like ES File Explorer, to your Android device
  5. Now navigate to your APK file using the file explorer app, click on your file, and click install to start the installation

Injecting a Device ID

As we mentioned above, you need to include the osig file in your app project before building it. However, what if you get a new Gear VR and want to install your app on that device too? You’d have to re-build your app each time, which is a bit of a hassle. That’s why the guys over at SideloadVR created a standalone injector, which allows you to add osig files directly into an already existing APK file! I was so happy when I found out about this possibility, but it might be a bit tricky to use for some since it involved using the command line, so let me explain how it works.

  1. Download and unzip the SideloadVR Standalone Injector for Windows (no OSX support so far)
  2. Write down the path to the directory where you just unzipped the Standalone Injector
  3. Copy both your APK file and your osig file to the Standalone Injector directory
  4. Install the latest Java Runtime Environment (JRE)
  5. Open cmd and type: cd C:/path/to/your/standalone/injectorAnd press ENTER
  6. You now have to type run.bat followed by the name of your APK followed by the name of your osig file, e.g. run.bat myapp.apk oculus_93846eu663hf82kfPress ENTER to start the injection process

It takes a few seconds, after which you’ll see a new APK file has appeared in the Standalone Injector directory with the signed_ prefix. This new APK file includes the new osig as well as all the osig files already present in the original APK.

Alternative distribution channels

Since this whole Device ID thing is often a bit annoying, several services have sprung up to help alleviate the pain of distributing your Gear VR app outside of the Oculus Store.

The first is the one I’ve mentioned earlier already, SideloadVR. As a developer, you can fill in a short form, after which they will contact you. You then upload your APK to their server, and users upload their own osig files. SideloadVR then builds the user a custom APK which they can then install and run on their device.

A more recent player in this space is ConstructVR. What they do very well is that users no longer have to figure out their Device ID and create their own osig file, since the ConstructVR app takes care of all this. On top of that, the ConstructVR platform allows you to manage Device IDs, only adding the ones you want in there and removing the rest of them, where SideloadVR just keeps stacking Device IDs without offering the ability to remove some. Downside is that ConstructVR is not free, but it’s more than worth the fee.

Oculus also offers some testing and release channels to which you can invite users before you submit your app to the store. You do this by creating a new Gear VR app on the Oculus Dashboard page and then uploading your APK to one of the testing channels (ALPHA, BETA or RC) on the Builds tab. You can then click the little + button to add users to test out that specific version of your app. I personally have never used this approach, but it seems like it could be a decent alternative.

And that concludes this little story. If there are still questions, feel free to ask them in the comments below.