Getting Started Guide. Version

Transcription

1 Getting Started Guide Version

2 2 Introduction Oculus Platform Copyrights and Trademarks 2017 Oculus VR, LLC. All Rights Reserved. OCULUS VR, OCULUS, and RIFT are trademarks of Oculus VR, LLC. (C) Oculus VR, LLC. All rights reserved. BLUETOOTH is a registered trademark of Bluetooth SIG, Inc. All other trademarks are the property of their respective owners. Certain materials included in this publication are reprinted with the permission of the copyright holder. 2

3 Oculus Platform Contents 3 Contents Server-to-Server API Basics...4 Requests and Messages... 6 Migrating from a Previous Version... 8 Development Environment and Configuration...9 Initializing and Checking Entitlements...11

4 4 Server-to-Server API Basics Oculus Platform Server-to-Server API Basics Some platform features use server-to-server (S2S) REST API calls to perform actions not appropriate to be sent from client devices. These APIs are provided to ensure a secure interaction between your back-end servers and the Oculus Platform. For example, we use these APIs to make in-app purchases more secure and prevent fraud. Details about individual S2S calls can be found in the features pages of the Developer Guide. This page describes the two types of access tokens required to make S2S calls, the User Access and App Access tokens. App Access Token The App Access Token is a string that your back-end uses to identify itself as a trusted resource. The App Access Token should never be shared with the client-side app. The string is (OC $APPID $APPSECRET) where $APPID and $APPSECRET are application specific values found on the API tab in the Developer Console. The $APPSECRET may be changed in the event that your credentials are compromised or you need a fresh set of API credentials. Changing the App Secret will revoke permissions from the previous App Secret. When calls originate from a trusted server and are in reference to specific user, the App Access Token will be used and the Oculus ID will be passed as a URI parameter. For example, during gameplay a user may unlock a rare achievement. Due to the achievement's desirability you have configured the achievement as Server Authoritative, meaning only your trusted server can unlock the achievement. In this scenario your trusted server will make a REST call, using the App Access Token and Oculus ID, to unlock the achievement on behalf of the user. User Access Token The User Access Token is user-specific string that identifies a user and allows your back-end server to act on their behalf. The User Access Token is retrieved by sending a request to ovr_accesstoken_get(). The token will be returned as a response. This token can be passed from the client to your backend. The User Access Token can be used when interacting on behalf of a user, or in reference to a specific user. For example, after a server-hosted multiplayer match may want to update a leaderboard with the results of the match. In this scenario, your server would make a call to update the leaderboard entry for each user with the results of the match using the User Access Token to identify the user. Forming the API Calls Each API call made to the Oculus APIs should be formed based on the information on the features pages, but there are some general similarities to be aware of. Most calls will ask you to reference the $AppID in the URI of the call. For example, when verifying that a user owns an IAP item: curl -X POST -d $USER-ACCESS-TOKEN This is the same App Id mentioned above that is found in the API tab of Developer Center.

5 Oculus Platform Server-to-Server API Basics 5 Example S2S Call Let's review the process to form an S2S REST call using the information on this page. For this example, we'll use the Oculus S2S API to unlock a client-authoritative achievement that a user has earned. This example assumes that you have already created the achievement and integrated the hooks into your app, additional information can be found on the Achievements page. 1. Retrieve the User's ID - To call the Oculus APIs on behalf of a user you need to include the Oculus ID identifying that user. Call ovr_user_getloggedinuser on Native or Platform.User.GetLoggedInUser on Unity to retrieve the ID. It will be returned as the ovrid of the user. 2. Pass the Information to your Trusted Server - Once you've retrieved the Oculus ID, pass the ID and the api_name of the achievement you wish to update or unlock from the client device to your server. 3. Form the App Access Token - Use the following credentials that we retrieved from the API section of the Developer Center: App Id App Secret - 5f8730a4n51c5f8v8122aaf971b937e7. You can then form the App Access Token as: OC f8730a4n51c5f8v8122aaf971b937e7. 4. Call the API to Unlock the Achievement - Once you've retrieved the information from the client device and formed the App Access Token, send the API call to unlock the achievement. $ curl -d "access_token=oc f8730a4n51c5f8v8122aaf971b937e7" -d "api_name=my_simple_achievement" -d "force_unlock=true" The API will respond with: "id":"$userid", "api_name":"my_simple_achievement", "just_unlocked":true Letting you know that your request was successful. Pass a message back to the client indicating that the achievement has been successfully unlocked.

6 6 Requests and Messages Oculus Platform Requests and Messages The Platform SDK uses a message queue to interact with Native apps. This page describes the concept of the queue and how to retrieve messages and information. Note: The information on this page only applies to native apps. Making a Request SDK requests are how you asynchronously send information to, or request information from, the Oculus Platform. Your client initiates these requests by calling the SDK method that corresponds to the action you want to perform. A complete list of the requests you can make are found on the Requests page of our Reference. For example, let s retrieve the Oculus ID of the user that is currently logged in. Call the following SDK method: OVRP_PUBLIC_FUNCTION(ovrRequest) ovr_user_getloggedinuser(); We'll check for a response and the Oculus ID a little later on. Checking the Message Queue Your app should be contantaly checking the message queue for notifications and messages from the Platform SDK. Messages are responses to some action from your app, while notifications are initiated external systems or other users. We recommend that you check the queue every frame for new messages and notifications. To poll the message queue, call ovr_popmessage(). If a message is present, an ovrmessagehandle object will be returned as a pointer to a message or notification. You should poll the queue until null is returned. Retrieving Messages and Notifications Off the Queue After you ve checked the queue and retrieved a message pointer, you'll check what kind of data the message contains. This will determine how your app handles the information contained in the message. Determine the Message Type Call ovr_message_gettype with the pointer you retrieved to check the message type. From our earlier example, let's assume the message type returned is ovrmessage_user_getloggedinuser indicating that this message is a response to a request for the currently logged in user's Oculus ID. Note: Notification message types won t be in response to a request initiated by that user s client. For example, a message of ovrmessage_notification_networking_peerconnectrequest would result from another user attempting to establish a networking request. A full list of message types that can be returned can be found in the OVR_MessageType.h SDK file. Retrieve the Message Data Once you've determined the message type, check to see if the message is an error by calling ovr_message_iserror() passing the pointer to the message. If the response is an error you should handle the error in your app. Check to see if the message is an error before you retrieve any message data.

7 Oculus Platform Requests and Messages 7 If there was no error, our example message will contain a payload of type ovruserhandle. Extract the payload from the message handle with: ovr_message_getuser (const ovrmessagehandle obj) The method to retrieve the message payload will typically follow the format 'OVR_Message_' followed by the message type. A full list of functions to retrieve a message can be found in the OVR_Message.h file of the Platform SDK. Each message type maps to a data model type telling you exactly what data to expect in the payload. A complete list of the data models that may be returned can be found on the Models page. Once you ve retrieved the message payload call ovr_freemessage() to free the message from memory. Making Multiple Requests If you re making multiple requests to the same SDK method, you ll want to be able to associate the responses with the request that you made. For example, you may wish to retrieve data from multiple leaderboards to display to a user. In this scenario you ll associate a request id with each call that you make. Then, when you ve checked the queue and retrieved a message type that matches your leaderboard requests, call ovr_message_getrequestid() with the message pointer you received and compare the response to the message ids that you set when making the requests. When you match the message to the request you made, retrieve the payload and handle the data as described above. Example Implementation Our Sample Apps contain examples of how functioning apps handle messages. CloudStorage is our native sample app that handles multiple types of messages.

8 8 Migrating from a Previous Version Oculus Platform Migrating from a Previous Version Migrating to Platform SDK If you're migrating to a recent version (v1.10+) from a previous SDK version (v1.9 or earlier). Native Gear VR only - After downloading the latest Platform SDK version, you'll need delete all svcloader.jar, libovrplatform.so, and svcjar.jar files manually. If You're Currently Using Version 1.0 or 1.1 If you're currently using version 1.0 or 1.1, find and replace the following variables in the ovrmatchmakingcriterion class: Remove System.LoadLibrary() calls from your app. Change paramterarraycount to parameterarraycount. Change paramterarray to parameterarray. For complete information about each release, please see the Current Platform SDK Version Release Notes.

9 Oculus Platform Development Environment and Configuration 9 Development Environment and Configuration Configure your local development environment for building VR applications. This page will also review the steps to prepare your app to run locally during development. Configure Your Unity Development Environment Configure your development environment by adding Oculus Platform Support to your Unity project. 1. Open the Unity editor and import the OculusPlatform Unity package. Navigate to Main Menu / Assets / Import Package / Custom Package. 2. Copy the App Id that you retrieved from the Developer Center and add it to the project in Main Menu / Oculus Platform / Edit Settings / Oculus App Id. Configure Your Native 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 Rift Development Environment 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 for your Rift app. The SDK download provides a loader that enables DLL signature verification and graceful detection of the Oculus Runtime. To use the loader: 1. In your Visual C++ project, open the project Properties, expand the Linker tab, and select Input. Then, add the loader library (LibOVRPlatform32_1.lib or LibOVRPlatform64_1.lib) to Additional Dependencies. 2. Add the cpp loader file (InstallFolder/Windows/OVR_PlatformLoader.cpp) to your project. Configure your Gear VR Development Environment Note: The steps in this section are only if you're creating a Gear VR app. Configuring Android Studio for your Gear VR project is the first step in integrating the Oculus Platform SDK for your Gear VR app. There are two SDKs that you need to apply in the SDK Manager (Tools > Android > SDK Manager). 1. 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). 2. 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

10 10 Development Environment and Configuration Oculus Platform check that you'll integrate in Initializing and Checking Entitlements on page 11. This section is not required unless you are planning to run your app locally during development. 1. Create an application as described in Creating and Managing Apps. 2. Upload a binary package for that application. The package does not have to function in any way during development, it just needs to exist. 3. Add each developer who will be working on the application to the developer role of that binary. Each developer can verify by checking that they see the build in their build list. 4. 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 VR, LLC\\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. Integrating the SDK The next step is to implement the initialization functions and Entitlement Check. See the Introduction to the Platform SDK page for information about these steps.

11 Oculus Platform Initializing and Checking Entitlements 11 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 Unreal Developer Guide for information about using the Unreal development platform. 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. 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 app credentials and suggest that

12 12 Initializing and Checking Entitlements Oculus Platform 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. // 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)

13 Oculus Platform Initializing and Checking Entitlements 13 // 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 app credentials and 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 on page 6 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 when implementing Matchmaking where you can run multiple apps on the same box to test your integration. To initialize the SDK in standalone mode, call ovr_platform_initializestandaloneoculus. Initializing in standalone mode limits the SDK from connecting any locally running Oculus Service processes. 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 username and password. OVRPL_PUBLIC_FUNCTION(ovrRequest) ovr_platform_initializestandaloneoculus( const ovroculusinitparams *params) Where the ovroculusinitparams are formed: typedef struct ovrplatformstructuretype stype; const char * ; const char *password; ovrid appid; const char *uriprefixoverride; ovroculusinitparams; ovroculusinitparams values are:

14 14 Initializing and Checking Entitlements Oculus Platform stype - Credential struct type, must be: ovrplatformstructuretype_oculusinitparams - address associated with Oculus account. password - Password for the Oculus account. appid - ID of the application (user must be entitled). uriprefixoverride - optional override for Note: Standalone mode is only available for native apps at this time. Features Integration Once you re finished configuring the SDK base and have verified that the user owns your application, you can integrate the SDK features. Please see the Developer Guide to learn about the different features available in the Platform SDK.