Entitlement Check for Oculus Store Apps

Note: You are viewing the Unity version of this topic. To view this topic for native development, see Entitlement Check for Oculus Store Apps (Native). To view this topic for Unreal development, see Entitlement Check for Oculus Store Apps (Unreal).

One of the requirements to sell an app in the Oculus Store is that you verify the user purchased or obtained your app legitimately. This check is called the entitlement check. You should make the entitlement check within 10 seconds of the user launching your app.

The entitlement check does not require the user to be connected to the Internet. Also, you must handle a failed entitlement check in your app code. A failed entitlement check won’t result in any action on its own. For example, if the check fails, you could show the user an error message and quit the app.

Optionally, you can associate an app entitlement with a Custom Item, which the user can display in their Oculus Home as a reward to customers to purchase your app in the Oculus Store.

Perform the Entitlement Check

The first step to integrating platform features is implementing the initialization function. There are two initialization functions you can call with your App Id. One is synchronous and runs on the thread you initialize on, the other is asynchronous and allows you to perform other functions, including calls to the Platform SDK, while the SDK is initializing. You should use the asynchronous method for better app performance and less state management, especially on mobile.

  • Synchronous - Platform.Core.Initialize()
  • Asynchronous - Platform.Core.AsyncInitialize()

For example:

Platform.Core.AsyncInitialize(appID)

When using the asynchronous call, the SDK is placed in an intermediate initializing state before full initialization. In this initializing state you’re able to run other processes, including making calls to asynchronous Platform SDK methods. Requests made to the Platform SDK in the initializing state will be queued and run after the SDK finishes initializing.

Then, after you’ve made the call to initialize the SDK, verify that the user is entitled to your app. This check must be made within 10 seconds of the user launching the app.

Platform.Entitlements.IsUserEntitledToApplication().OnComplete(callbackMethod);

After retrieving the response to the check, you’ll need to handle the result. The following example immediately quits the application if the user is not entitled to your app. You may wish to handle the situation more gracefully by showing the user a message stating that you were unable to verify their credentials, suggest that they check their internet connection, then quit the app. You may not allow the user to proceed in your app after a failed entitlement check.

void callbackMethod (Message msg)
{
  if (msg.IsSuccess)
     {
       // Entitlement check passed
     }
        else
     {
       // Entitlement check failed. Quit app
     }
 }

Entitlement Check Best Practices

In order to properly perform entitlement checking, follow these recommendations:

  • Use AsyncInitialize() rather than Initialize() for Android 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 App Id in OculusPlatformSettings in the Unity Editor, or call AsyncInitialize() with an explicit AppId argument. For mobile developers: If you need to run mobile applications in the Unity Editor, you must provide Oculus login credentials (username/password) in the OculusPlatformSettings. Simply setting App Id isn’t sufficient.

Entitlement Check Sample Code

Here is an sample entitlement check class for a Unity application:

using UnityEngine;
using Oculus.Platform;

public class AppEntitlementCheck: MonoBehaviour {

  void Awake ()
  {
    try
    {
      Core.AsyncInitialize();
      Entitlements.IsUserEntitledToApplication().OnComplete(EntitlementCallback);
    }
    catch(UnityException e)
    {
      Debug.LogError("Platform failed to initialize due to exception.");
      Debug.LogException(e);
      // Immediately quit the application.
      UnityEngine.Application.Quit();
    }
  }


  // Called when the Oculus Platform completes the async entitlement check request and a result is available.
  void EntitlementCallback (Message msg)
  {
    if (msg.IsError) // User failed entitlement check
    {
      // Implements a default behavior for an entitlement check failure -- log the failure and exit the app.
      Debug.LogError("You are NOT entitled to use this app.");
      UnityEngine.Application.Quit();
    }
    else // User passed entitlement check
    {
      // Log the succeeded entitlement check for debugging.
      Debug.Log("You are entitled to use this app.");
    }
  }
}

See a more detailed example in the Entitlement Check Sample Application.

You can perform additional user verification if you want to verify the identity of the user to your back-end server. User Verification provides a cryptographic nonce you can pass to verify that the user’s identity. This method does not replace the entitlement check. For more information on how to verify the user, see User Verification.

Test Entitlement Check on Oculus Devices

Test your entitlement check to ensure that your application is up to VRC standards for uploading to the Oculus Store.

Enable Developer Mode

This only needs to be done once per device.

To set up an Oculus Rift for development, see the Rift Native SDK documentation.

  1. Turn on your Oculus Quest device and open the Oculus application on your phone.

  2. Tap Settings in the lower right corner.

  3. Select device, and allow your Oculus application to connect to your device.

  4. Tap More Settings > Developer Mode and then toggle Developer Mode ON.

  5. Restart your Oculus Quest device.

You may need to restart your headset after doing these steps. Once done, there will be a new option in your headset library called “Unknown Sources”.

Test Entitlement Check

Have the application installed and make sure it opens properly before checking entitlements.

  1. Go to the Getting Started API page for your application in the Developer Dashboard.

  2. Replace your App ID with a random string of numbers.

  3. Try launching the app.

  4. The entitlement check should fail, and show an error message to the end user or enter a limited demo mode.

Or, you can log out of the entitled Oculus account and attempt to launch the application.