Native Development - Get Started with the Platform SDK

This guide will walk you through the basics of setting up your development environment, initializing the SDK, and checking the user’s entitlement.

The Sample Apps are available as reference when implementing the steps on this page.

Prerequisites

Before you can integrate the Platform SDK, you’ll need to create an app, and have the associated App ID. To create an app see the information on the Creating and Managing Apps page.

When you have created your app, visit the Dashboard API page and choose your app or on developer.oculus.com under Manage > App Name, select Getting Started API. The App ID will display in the middle of the screen, You’ll need your App ID to call the initialization APIs described in the next few sections. The following image shows an example of where to find the App ID.

Configure Your Development Environment

The steps to configure your environment will be different depending on the type of app you’re building. Follow the steps for the app you’re building.

Configure Your Development Environment for Rift

Note: The steps in this section are only if you’re creating a Rift app.

Configuring Visual Studio for your Rift project is the first step in integrating the Oculus Platform SDK. Use the following steps to configure Visual Studio for Rift development. You will need to add the path to the Include directory and the platform SDK libraries, and change a couple of settings. In addition, the SDK download provides a loader that enables DLL signature verification and graceful detection of the Oculus Runtime. To configure Visual Studio to use the platform SDK, complete the following steps:

• Download the Platform SDK if you haven’t already.
• Extract the contents of the download.
• Open Visual Studio and create a new C++ console application, or open an existing project.
• Right click the project and select Properties.
• Configure the path to the header files. To do this, under C/C++ > General, find Additional Include Directories, and select <Edit...>. Navigate to and select the platform SDK include directory [platform-sdk-extraction-dir]/OVRPlatformSDK_v1.28.0/Include.

Change the settings to not use precompiled headers and the mode to permissive. To do this:

• Under C/C++ > All Options, find the Conformance mode entry and change the setting to No.
• Find the Precompiled Headers entry, and use the drop-down to change the setting to Not Using Precompiled Headers.

Next, configure the linker and the platform loader. To do this:

• Under Linker > General, find Additional Library Directories. Select <Edit...>. In the dialog, click the New Folder icon and add [platform-sdk-extraction-dir]/OVRPlatformSDK_v1.28.0/Windows to the list.
• Configure additional dependencies by choosing Linker > Input. Under Additional Dependencies, click <Edit...> and add the name of the loader library, LibOVRPlatform32_1.lib or LibOVRPlatform64_1.lib, depending on whether your project is 32 or 64 bit.
• Add the cpp loader file [platform-sdk-extraction-dir]/Windows/OVR_PlatformLoader.cpp to your project. To do this, select your project, right click and select Add Existing Item. Navigate to the platform loader project and select it.

Finally, add the platform include statement, #include "OVR_platform.h", to main.cpp and compile your project. It should compile without errors.

Configure Your Development Environment for Mobile Development

Note: The steps in this section are only if you’re creating a mobile app.

Configuring Android Studio for your mobile project is the first step in integrating the Oculus Platform SDK for your mobile app. There are two SDKs that you need to apply in the SDK Manager, Tools / Android / SDK Manager.

• The Oculus Platform SDK provides a loader that enables .so signature verification and graceful detection of the Oculus Runtime. To use the loader, add the SDK location to the manager ([InstallFolder]/Android/libs/armeabi-v7a/libovrplatformloader.so).
• Then, add the Android NDK (found in the SDK Tools tab of the SDK Manager). The NDK is a set of tools that allows you to use C++ code on Android devices. The NDK also manages device activities and allows your app access to device sensors and inputs.

Configuring Your App for Local Development

The configuration steps in this section will allow developers to run local builds of the application during the development process. This process is required, otherwise local versions of the app will not pass the entitlement check that you’ll integrate below.

• Add the user(s) to your org. See the Manage Your Organization and Users for information about managing your organization.
• If some of your developers are not part of the application’s organization, and they need to run your application outside the normal install directory. Add the registry key AllowDevSideloaded as DWORD(1) to the registry folder at HKLM\SOFTWARE\Wow6432Node\Oculus\Oculus

This does not bypass having a valid entitlement, it just bypasses the directory check. Once the steps above are completed the entitlement check will succeed when running a local build of your application.

Initialize the SDK and Perform the Entitlement Check

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.

Synchronous

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 should be made within 10 seconds of the user launching the app.

// Initialization call
#define OCULUS_APP_ID "some-app-id"

// Initialization call
if (ovr_PlatformInitializeWindows(OCULUS_APP_ID) != ovrPlatformInitialize_Success)
  {
    // Exit.  Initialization failed which means either the oculus service
    // isn’t on the computer or the DLL is not valid.
  }

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

Asynchronous

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

// Initialization call

#define OCULUS_APP_ID "some-app-id"
if (ovr_PlatformInitializeAndroidAsynchronous(OCULUS_APP_ID) != 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.

// 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.

What is the Entitlement Check?

Verifying that the user is entitled to your app is required when you sell an app on the Oculus Store. This check verifies that the copy of your app was purchased legitimately. Once purchased, the user receives an entitlement for your app, which you can associate with a Custom Item as a reward.

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.

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.

Initializing 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. 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:

Checking Errors

Sometimes things go wrong and you’ll want to know what happened. Checking the error code and message can provide insight to what happened. Some errors have an accompanying message that you can display to your users if the error results from their actions.

To check for an error:

With every request you make to the Oculus Platform, check to see if the message is an error by calling ovr_Message_IsError(). If the message is an error, then call ovr_Message_GetError() to retrieve the error object. The error object contains information you can use to debug the reason for the error:

• ovr_Error_GetHttpCode() returns an http code for the request, such as 400 or 500.
• ovr_Error_GetCode() returns a code representing the class of error. For example, all errors with 100 as the code are invalid parameter errors. Different errors may map to the same code. Review the error message for specifics of what went wrong. For example, an invalid id or missing required param would both return errors with 100 as the code.
• ovr_Error_getMessage() returns a the raw error as a JSON string, which include the fields:
  • message: the description of the what went wrong and possibly how to debug/fix the issue.
  • code: It typically matches ovr_Error_GetCode, except in cases when there is a conflict in client/server code. Use the value from ovr_Error_GetCode instead.
  • fbtrace_id: Helpful for when you are contacting support. We use this internally to find more information about the failing request. ovr_Error_getDisplayableMessage() returns a message that you may optionally display to the user. It has none of the technical information obtained from ovr_Error_getMessage. An example displayable message could be You're not yet ranked on this leaderboard. if you are querying for the leaderboard of the app that the user has not been placed in. The value may be empty in the cases where it is a developer-caused error rather than a user-caused error.