Unity Engine Entitlement Checks for Gear VR and Rift

Lack of entitlement checks is the most common error encountered during the application submission technical review process. As such, we wanted to provide you with the resources and best practices to ensure you do not experience this error when you submit your application to the Oculus Store.

While implementing entitlement check functionality is similar on both the mobile (Gear VR) and PC (Rift) platforms, there are a few specific setup differences that must be taken into account for each.

This blog provides all the necessary resources for Unity developers. If you are an Unreal developer, go here for entitlement check best practices. If you are a Native developer, go here.

Gear VR Entitlement Best Practices

As specified in the platform guide for Unity, there are two different methods available for initializing our platform SDK in your application:

1. Synchronous - Platform.Core.Initialize()
2. Asynchronous - Platform.Core.AsyncInitialize()

We strongly recommend that developers use the asynchronous method for initializing their mobile applications, as calls to the Platform SDK can fire while it initializes, which allows for other functions to run in parallel. This can result in better app performance, especially on mobile, along with less state management.

Recently, we made a few updates to our documentation to reflect a change in our evaluation of entitlement checks on Gear VR. Below is a list of the new steps that are required on your end for proper entitlement check functionality as well as some clarity on how to implement them in your application.

Recommended Entitlement Check Settings

• Use AsyncInitialize() rather than Initialize() for mobile apps. This is important because AsyncInitialize() does not block the initialization code, which allows your application to load faster. In addition, AsyncInitialize() does not throw an exception on Android if the initialization failed.
• Surround the platform API initialization code with a try/catch block, and treat any exceptions that are caught as if the entitlement check failed.
• Set your Application ID in OculusPlatformSettings in the Unity Editor, or call AsyncInitialize() with an explicit AppID argument. If you need to run Gear VR applications in the Unity Editor, you must provide Oculus login credentials (username/password) in the OculusPlatformSettings. Simply setting the Application ID is not sufficient.

Proper Entitlement Check Setup on Rift and Gear VR

Below is an example entitlement check implementation that will work across both platforms. Please note that while Gear VR requires an asynchronous implementation for entitlement checking to function properly, Rift applications can utilize either method based on the needs of your application and pass entitlement check functionality successfully.

When incorporating this code into your project, be aware that you must choose one place to populate your application's user ID: either directly in the code above or within Unity in the OVRPlatformSettings menu. Providing the ID in both places for your project will result in a 'clobbering' of the IDs, which will cause an entitlement check failure for your application.

Using the CLI Tool to Integrate the Entitlement Check on Rift Applications

The Oculus Platform Command Line Utility offers a faster way to upload and streamline manual processes associated with your applications. Below is an example entitlement code instrumentation option for quickly and easily adding entitlement checking to your Rift build.

The Rift upload example below uses the fictitious app "Rabbit Hole", as described in the CLI Tool documentation here.

• App ID: 10001234
• App Secret Token: 1234abcd
• Build Directory: C:\Rabbit Hole
• Launch File: C:\Rabbit Hole\bin\badrabbits.exe
• New Version: 1.1

To upload version 1.1 of Rabbit Hole to the RC release channel with injected entitlement check code, enter:

ovr-platform-util upload-rift-build -a 10001234 -s 1234abcd --add-entitlement-check -d "C:\Rabbit Hole" -l "bin\badrabbits.exe" -n "

Now our example application will have the correct entitlement code injected into the build.

Troubleshooting Entitlement Check Functionality

We've gone through just a few best practices and guides to help you ensure entitlement checks are implemented properly on your application. Here is a list of our top 4 tips to help you troubleshoot entitlement checks on your app:

• Make sure that you have purchased your application in the Oculus Store. You will need to go to the store page for that application and select buy to get the actual entitlement.
• If the application is not present in your Oculus Library under “my preview apps” please close Oculus Home, restart it and then log out and back in again, the application should now be present in your library.
• If you are side-loading your application (Rift only), please read this blog post here for steps you can take to ensure your application is getting proper entitlement functionality.
• Make sure that you are entitled to your application in your developer dashboard by going to, “settings→members→your admin account→manage apps” and verify that there is a check mark next to the application in question.

For more information on entitlement checks please see the available documentation on the developer center.