Some months ago I published a guide for all Unity developers on how to request Android permissions for the Vive Focus Plus, because it took me a while to sort out how to do it to access the camera stream to do augmented reality on that headset. Recently, I had a similar problem with the Oculus Quest, not to access the cameras (it is not possible, the applications can’t see them for privacy reasons), but to save a file on the storage from Unity. I spent some time understanding how to do perform this operation, so I’ll write this little how-to for all the VR devs like me that find themselves in the same situation.
What are Android permissions?
A quick recap for the few devs that have never had to deal with Android permissions. Android is an operating system that is based on Unix and so cares a lot about the safety of its users. An application can’t do with the phone what it wants, but for those features that can harm the user in a way or in another, it must explicitly ask the user the permission to do that. For instance, if an application wants to read your geolocation data, it must explicitly ask you permissions, because it could use that data to stalk you. The same if it wants to access your camera because it could shoot photos of your personal life. Also, access to the external storage is forbidden, …and so on.
“Android permissions” are that mechanism that handles all the requesting and granting permission to use potentially dangerous features. Every time that you see a popup asking if an application can access something, it is the Permissions engine at work. You can read more about it here.
What happens if you don’t ask for permissions?
It simply happens that things do not work as expected. It is interesting to notice that the operating system will silently complain about your unauthorized request (you can spot it by reading Android Logcat), but your user won’t experience any crash or error box. From his/her point of view, nothing bad has happened, but at the same time, the app is not doing everything it is supposed to do.
This is very frustrating while you’re developing stuff because, for instance, you want to create a file on your Oculus Quest, and then the file doesn’t get created, but the program throws no exception, and you spend hours scratching your head asking yourself what’s happening. If you’re in a similar situation, most probably you’re forgetting about asking permissions (and an analysis of Logcat while you run the application can spot it easily).
Why do we care about it in XR?
Well, for simple VR experiences, you don’t need to care about this. But as soon as you need access to cameras, mic, storage, gallery of photos, Blutooth, etc…. you need to know how to handle permissions.
How to obtain permissions for Oculus Quest in Unity
Time to dig into the main topic of this post. So, how do you obtain permissions for your Oculus Quest in Unity? There are basically three ways: one is automated, another one is manual, and the third one is the low-level one.
The automated way
The automated way is what saves you most of the times. Basically what you have to do to activate it is… nothing. You just write your code and Unity understands automatically that your program must request some permissions and does everything that is needed to request them, without having you to do anything.
How is that possible? Well, it automatically detects if you’re using certain classes and if it spots them in your code, it does everything on itself. For instance, if you use the class Microphone, when Unity builds your APK, it adds in the manifest and in the code all the necessary procedures to make your app obtain the RECORD_AUDIO permission from its users.
How can you know that Unity is going to do that? Well… you just discover it by running your application and see that at the first run, it asks for the required permissions. If you’re in this case, you’re lucky, you have to do nothing.
The manual way
The manual way is the annoying one: the lazy Unity won’t do the work for you, because you’re not using the magic classes that trigger the automated way. For instance, you’re going to use another class to handle the microphone; or, like me, you want to read or write some files to the external storage folders, and you want to use the classical System.IO classes. In this case, you have to do everything by yourself. This requires two easy steps.
Step 1: Ask the permission at runtime
The new rules from Android 6.0 require that you ask the permissions at runtime, and not at install time anymore. So, inside the code of your experience, you have to verify if the user granted the permissions to you and if not ask him for the permissions.
The class UnityEngine.Android.Permission makes our life easy in doing this. You have just to call one method (Permission.RequestUserPermission) to ask the operating system to take care of everything. For instance, this is the code that you have to write when you want the user to give the permission to use the microphone to your app (probably in the Start() method of some behaviour):
if (!Permission.HasUserAuthorizedPermission(Permission.Microphone))
Permission.RequestUserPermission(Permission.Microphone);That’s it. Easy peasy.
Step 2: Add the permission to the manifest
Android requires you to also add the features that you request to the Android manifest.
What you have to do is:
- Install Oculus Unity plugin, if you haven’t done it yet
- Select in the menu Oculus -> Tools -> Create store-compatible AndroidManifest.xml
- The above step has created a file called AndroidManifest.xml in the path Assets/Plugins/Android of your project. Open the file with visual studio
- Under <category android:name=”android.intent.category.INFO” />, add <category android:name=”android.intent.category.LAUNCHER” /> . You must add this if you want the “Build and Run” feature to work while developing your application. This line should be removed before you publish the app to the Oculus Store, though.
- After the </application> tag, add the permissions that you need, in the format <uses-permission android:name=”android.permission.NAME_OF_THE_PERMISSION” />
If you want an example AndroidManifest file with the permissions I used to read and write to the storage in a recent app of mine, here you are!
After you’ve written this, you’re done! You’ll notice that after you build and run, when the Permission.RequestUserPermission code gets executed, a popup will ask the user the permission for the feature you requested. You did it!
The low-level way
If for whatever reason the above methods don’t work, the only thing that you can do is create a native Android plugin, where you ask the permission within a Java plugin that you embed in your project.
This is a very nerdy and quite complicated topic, and it is a bit too much for the scope of this article. I did it once for handling Bluetooth inside an Android app in the past, and it is doable, but it requires some nerd skills. If you’re forced to do this, you can refer to this article on Unity native plugins and this one on Android Permissions in Java. Stay strong, you can do it!
And that’s it, I hope I have explained you well the topic of Android Permissions on the Oculus Quest, and to have spared you VR developers some headaches. If it is the case, please subscribe to my newsletter and add me on Twitter! Cheers 🙂
(Header image from an Image by Oculus)