Initializing and Checking Entitlements

Once you’ve defined your app in the Developer Center, you can start integrating the SDK into your app. The first step in integrating the SDK is using your App Id to initialize the SDK and perform the entitlement check to ensure the user's copy of the app is legitimate.

This page will walk you through the steps required to use the Platform SDK in native and Unity development environments. Sample Apps are available as reference when implementing the steps on this page.

Note: Please see the Oculus Platform Features and Online Subsystems page for information about checking entitlements in Unreal.

What is the Entitlement Check?

Verifying that the user is entitled to your app is the only required step to use the Platform SDK. This check verifies that the copy of your app is legitimate. The entitlement check does not require the user to be connected to the Internet. In the event of a failed check, you should handle the situation in your app. For example, show the user an error message and quit the app. A failed entitlement check won’t result in any action on its own.

No matter what development method you’re using or platform you're developing for, you need to include the entitlement check.

Additional user verification is available 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.

Entitlement verification is required to distribute apps through the Oculus Store.

Integrate the SDK - Unity

The first step to integrating the SDK 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. We recommend using the asynchronous method for better app performance, especially on mobile, and less state management.

  1. Synchronous - Platform.Core.Initialize()
  2. 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);
Note: With older versions of Unity, you may need to call Request.RunCallbacks() to process the callbacks and retrieve the results of the check.

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.IsError)
       {
          // Entitlement check passed
       }
     else
       {
          // Entitlement check failed
       }
    }

Gear VR only - If you’re testing your Gear VR app in the Unity editor you’ll need to set a test token. Select Oculus Platform / Platform Settings / Paste Token. You can retrieve your token from the API page on the Developer Center.

Integrate the SDK - Native

The first step to integrating the SDK 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. We recommend using the asynchronous method for better app performance, especially on mobile, and less state management.

  1. Synchronous:
    • Native Rift - ovr_PlatformIntializeWindows()
    • Native Gear VR - ovr_PlatformInitializeAndroid()

    The following example shows the synchronous initialization call for a Rift app, with another call to ovr_Entitlement_GetIsViewerEntitled(). The second call is the entitlement check that verifies that the user owns your app. Both steps are required to successfully initialize the SDK. The entitlement check must be made within 10 seconds of the user launching the app.

    // Initialization call
                if (ovr_PlatformInitializeWindows(appID) != ovrPlatformInitialize_Success)
                {
                // Exit.  Initialization failed which means either the oculus service isn’t on the machine or they’ve hacked their DLL
                }
                ovr_Entitlement_GetIsViewerEntitled();

    When the SDK has finished initializing, a ovrMessage_PlatformInitializeWindows message will be sent to the queue.

  2. Asynchronous:
    • Native Rift - ovr_PlatformInitializeWindowsAsynchronous()
    • Native Gear VR - ovr_PlatformInitializeAndroidAsynchronous()

    The example below shows the asynchronous initialization call for a Gear VR game. 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.

    The second call in the example below is the entitlement check that verifies that the user owns your app. Both steps are required to successfully initialize the SDK.

    // Initialization call
    if (ovr_PlatformInitializeAndroidAsynchronous(appID) != ovrPlatformInitialize_Success)
      {
      // Exit.  Initialization failed which means either the oculus service isn’t on the machine or they’ve hacked their DLL
      }
      ovr_Entitlement_GetIsViewerEntitled(); 

    When the SDK has finished initializing, a ovrMessage_PlatformInitializeAndroidAsynchronous message will be sent to the queue.

After initializing the SDK with either initialization method and making the entitlement check, you’ll need to check the response of the entitlement check and 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.

// Poll for a response
while ((message = ovr_PopMessage()) != nullptr) 
  {
     switch (ovr_Message_GetType(message)) 
      {
        case ovrMessage_Entitlement_GetIsViewerEntitled:
    
          if (!ovr_Message_IsError(message))
             {
               // User is entitled.  Continue with normal game behaviour
             }
          else
            {
              // User is NOT entitled.  Exit
            }
       break;
    default:
   break;
       }
    }

Please see the Requests and Messages page for information on how native apps interact with the Platform SDK.

Initializing the SDK in Standalone Mode

Standalone mode allows you to initialize the Platform SDK in test and development environments. Standalone mode is useful for testing Matchmaking where you can run multiple apps on the same box to test your integration. Initializing in standalone mode limits the SDK from connecting any locally running Oculus Service processes.

Note: Initializing in standalone mode uses a different set of credentials from the other initialization processes. When initializing in standalone mode, use your Oculus developer account email and password.

Native Apps

To initialize the SDK in standalone mode, call ovr_Platform_InitializeStandaloneOculus with the OculusInitParams identified below.

OVRPL_PUBLIC_FUNCTION(ovrRequest) 
              ovr_Platform_InitializeStandaloneOculus(
              const ovrOculusInitParams *params)

Where the ovrOculusInitParams are formed:

typedef struct
{
ovrPlatformStructureType sType; 
const char *email; 
const char *password; 
ovrID appId; 
const char *uriPrefixOverride; 
} ovrOculusInitParams;

The Init Param values are:

  • sType - Credential struct type, must be: ovrPlatformStructureType_OculusInitParams.
  • email - Email address associated with Oculus account.
  • password - Password for the Oculus account.
  • appID - ID of the application (the user must be entitled to this app)
  • uriPrefixOverride - optional override for https://graph.oculus.com

Unity Apps

To initialize the SDK in standalone mode, call Platform.InitializeStandaloneOculus to initalize in standalone mode with the OculusInitParams identified below.

Where the OculusInitParams are formed:

{
public int sType;
public string email;
public string password;
public UInt64 appId;
public string uriPrefixOverride;
}

The Init Param values are:

  • sType - Credential struct type.
  • email - Email address associated with Oculus account.
  • password - Password for the Oculus account.
  • appID - ID of the application (the user must be entitled to this app)
  • uriPrefixOverride - optional override for https://graph.oculus.com