Oculus Go Development

On 6/23/20 Oculus announced plans to sunset Oculus Go. Information about dates and alternatives can be found in the Oculus Go introduction.

Oculus Quest Development

All Oculus Quest developers MUST PASS the concept review prior to gaining publishing access to the Quest Store and additional resources. Submit a concept document for review as early in your Quest application development cycle as possible. For additional information and context, please see Submitting Your App to the Oculus Quest Store.

Leaderboards Server APIs

The server-to-server (S2S) Rest APIs provide a secure channel to interact with Oculus platform services. For example, you might want to update an Oculus leaderboard after you host a multi-player match on your server. This topic provides details about the Oculus leaderboard-related server calls that you can make.

Message Basics

There are some server to server message basics you should be familiar with.

Server-to-Server Endpoint

All server-to-server requests are made to the following endpoint:

https://graph.oculus.com

Access Token

An access token is sent with every message and either authenticates the request as a valid server request or as a request on behalf a particular user. The access token can contain one of the following:

App Credentials

App credentials verify your server back-end as a trusted resource. These credentials should never be shared with a client-side app.

An access token with app credentials contains the App ID and App Secret from the API page in the developer dashboard in the following format: OC|$APPID|$APPSECRET.

You can generate a new app secret if your credentials are compromised or you need a fresh set of API credentials. If you change the app secret, the permissions of the previous app secret are revoked. Note that you must use an admin account to access the app secret from the API page.

Note: Older versions of Unity use .NET 3.5 or earlier, which does not support SSL certificates that use SHA2 and cannot be used for server-to-server requests.

User Access Token

A user access token verifies a request on behalf of a user is valid. Use a user access token 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 client-authoritative 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.

Retrieve the user token with the ovr_User_GetAccessToken() method.

The token will be returned as a response and can be passed from the client to your server. An access token with a user credentials contains OC and a long alpha numeric string similar to the following: OC12342GhFccWvUBxPMR4KXzM5s2ZCMp0mlWGq0ZBrOMXyjh4EmuAPvaXiMCAMV9okNm9DXdUA2EWNplrQ.

Additionally, you can retrieve your user token for testing purposes at the bottom of the API page in the developer dashboard.

App ID

Some server calls require an app ID, which you can find on the API page in the developer dashboard.

Note: The cURL examples demonstrate calls with the Windows command line. Other platforms may vary.

Create or Update a Leaderboard

Use this method to create a leaderboard, or update the properties of an existing one. You can use this method to specify or update localized display titles for the leaderboard. See the title_locale_map parameter for more details.

URL: https://graph.oculus.com/{app_id}/leaderboards

METHOD: POST

Example Request:

POST /1234757621998335/leaderboards/?api_name=best_leaderboard&sort_order=HIGHER_IS_BETTER&entry_write_policy=CLIENT_AUTHORITATIVE&title_locale_map={"en_US":"Soccer", "en_GB":"Football"}
HTTP/1.1
Host: graph.oculus.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

Example cURL Request:

$ curl -d "access_token=OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a" ^
-d "api_name=best_leaderboard" ^
-d "sort_order=HIGHER_IS_BETTER" ^
-d "title_locale_map={\"en_US\":\"Soccer\", \"en_GB\":\"Football\"}" ^
-d "entry_write_policy=CLIENT_AUTHORITATIVE" ^
-d "earliest_allowed_entry_time=1463875200"  ^
-d "latest_allowed_entry_time=1464480000" ^
https://graph.oculus.com/12347576219/leaderboards

Parameters:

ParameterParam TypeDescriptionType
access_tokenHeaderRequired. A bearer token that contains one of the following:
  • App credentials - the app ID and app secret separated by the pipe symbol
  • User credentials - the user access token
Use the app credentials when making a request on behalf of the server, and the user credentials when you make a request on behalf of the user client.
string
app_idPathRequired. Oculus app identifier found on the API page.integer
api_nameQueryThe unique API Name for the leaderboard. This is specified when you created the leaderboard.string
earliest_allowed_entry_timeQueryOptional. Enables leaderboards to have a time limit with a specific start time. If used, entries can only be posted after this time.integer that represents a Unix timestamp
entry_write_policyQueryRequired. Describes who is allowed to write entries - a client or the server. Enum, valid values are: "CLIENT_AUTHORITATIVE", "SERVER_AUTHORITATIVE"
latest_allowed_entry_time QueryOptional. Enables leaderboards to have a time limit with a specific end time. If used, entries can only be posted before this time. integer that represents a Unix timestamp
sort_orderQueryRequired. Describes the preferred method to sort the leaderboard; either by high or low score. Enum, valid vales are: "HIGHER_IS_BETTER", "LOWER_IS_BETTER"
title_locale_mapQueryOptional. JSON encoded map that specifies a locale as the key and the localized title as the value for that locale, or empty string ("") to clear the value. The locale should be formatted as an ISO-639 language code followed by the 2-letter ISO-3166 country code. example: {"en-US":"Soccer", "en-GB":"Football"} Note that:
  • Specifying a a non-empty value for a locale that doesn't exist in the map results in that locale being added.
  • Specifying a non-empty value for a locale that exists in the current map results in that locale being updated with the new value.
  • Specifying an empty string for a locale that exists in the current map results in that locale being deleted.
  • Specifying an empty string for a locale that doesn't exist in the current map has no affect on the map.
  • If a locale already exists in the map, you must explicitly specify it with a different value or an empty string for the value to change.
JSON-encoded string
is_publicQueryOptional. Indicates if the leaderboard is publicly visible. boolean
destination_api_nameQueryOptional. The api name of a destination to associate with this leaderboard. string
score_typeQueryThe score integer will be displayed based on this Enum value. The default is POINT. Enum, valid values are: "DISTANCE_IN_FOOT", "DISTANCE_IN_METERS", "PERCENTAGE", "POINT", "TIME_IN_MILLISECOND", "TIME_IN_SECOND"

Example Response:

{"id":"10742336355960170"}

Create or Update a Leaderboard Entry

Use this method to create an entry for a leaderboard, or update an existing one. When you call this method, you should:

  • Authenticate the call with the user token if the leaderboard is client authoritative, and do not provide a user ID.
  • Authenticate the call with the app token if the leaderboard is server authoritative. When provide the app token, you must also provide the user ID.

URL: https://graph.oculus.com/leaderboard_submit_entry

METHOD: POST

Example Request (server authoritative):

POST /leaderboard_submit_entry/?api_name=best_leaderboard&score=12345&extra_data_base64=T271bHVz&force_update=true&user_id=123402235207175
HTTP/1.1
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

Example cURL Request (client authoritative):

$ curl -d "access_token=OC1234OYRxTfgiFehJN4PrZBx4PH1D5SfGWn7z1ix06dpsZAhHPhN9z1F" ^
-d "api_name=best_leaderboard" -d "score=12345" -d "extra_data_base64=T271bHVz" -d "force_update=true" ^
https://graph.oculus.com/leaderboard_submit_entry

Parameters:

ParameterParam TypeDescriptionType
access_tokenHeaderRequired. A bearer token that contains one of the following:
  • App credentials - the app ID and app secret separated by the pipe symbol
  • User credentials - the user access token
Use the app credentials when making a request on behalf of the server, and the user credentials when you make a request on behalf of the user client.
string
api_nameQueryThe unique API Name for the leaderboard. This is specified when you created the leaderboard.string
score QueryRequired. The leaderboard value or score being submitted. integer
extra_data_base64QueryOptional. Extra metadata to store with the leaderboard entry. This can be used to specify information about the score. For example, in a driving game this may be what car was used. Decoded length can be, at most, 2048 bytes. string
user_id QueryRequired if you use the app access token to authenticate to the API. Indicate which user you are posting on behalf of. That user must have an entitlement to your app. When using a User Access Token, this field must not be set. string
display_scoreQueryThe formatted score that will be displayed in the leaderboard.string

Example Response:

The response contains a status, did_update indicates whether the entry was recorded or not. Entries will not be recorded if the user already has an entry on the leaderboard, the new score is worse than the old score, and force_update is false.

{"success": true,
"did_update": true}

Retrieve Data about a Leaderboard

Use this method to get the number of entries, write policy and sort order for the leaderboard.

URL: https://graph.oculus.com/{app_id}/leaderboards

METHOD: GET

Example Request:

GET /12347576219/leaderboards/?api_name=best_leaderboard
 &fields=sort_order,entry_write_policy,entry_count
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

Example cURL Request:

curl -G -d "access_token=OC1234f7a788b0c0b270f9691d0a06d5a5" ^
-d "fields=sort_order,entry_write_policy,entry_count" ^
https://graph.oculus.com/12347576219/leaderboards

Parameters:

ParameterParam TypeDescriptionType
access_tokenHeaderRequired. A bearer token that contains one of the following:
  • App credentials - the app ID and app secret separated by the pipe symbol
  • User credentials - the user access token
Use the app credentials when making a request on behalf of the server, and the user credentials when you make a request on behalf of the user client.
string
api_nameQueryThe unique API Name for the leaderboard. This is specified when you created the leaderboard.string
fieldsQueryRequired. A comma separated list of fields to retrieve. Possible values -
  • sort_order
  • entry_write_policy
  • entry_count
A comma-separated list of strings

Example Response:

{
    "data": [{
        "id": "1074273245960170",
        "sort_order": "HIGHER_IS_BETTER",
        "entry_write_policy": "CLIENT_AUTHORITATIVE",
        "entry_count": 2500
    }]
}

Retrieve Leaderboard Entries

You can retrieve leaderboard entries for users including the user ID, alias and profile URL, as well as the leaderboard rank, entry count, and more. When you call this method, you should:

  • Authenticate the call with the user token if the start_at param is one of the VIEWER options.
  • Authenticate the call with the user token if the filter param is FRIENDS.
  • Otherwise, authenticate the call with the app token.

URL: https://graph.oculus.com/leaderboard_entries

METHOD: GET

Example Request:

GET /leaderboard_entries/?api_name=best_leaderboard&fields=user{id, alias, profile_url}, rank, score, timestamp, extra_data_base64&filter=NONE&start_at=OFFSET&offset=10&summary=true&limit=2
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

Example cURL request:

$ curl -G -d "access_token=OC1234OYRxTfgiFehJN4PrZBx4PH1D5SfGWn7z1ix06dpsZAhHPhN9z1F" ^
-d "api_name=best_leaderboard" ^
-d "filter=NONE" -d "start_at=OFFSET" -d "offset=10" -d "summary=true" ^
-d "limit=2" ^
-d "fields=user{id,alias,profile_url},rank,score,timestamp,extra_data_base64" ^
https://graph.oculus.com/leaderboard_entries

Parameters:

ParameterParam TypeDescriptionType
access_tokenHeaderRequired. A bearer token that contains one of the following:
  • App credentials - the app ID and app secret separated by the pipe symbol
  • User credentials - the user access token
Use the app credentials when making a request on behalf of the server, and the user credentials when you make a request on behalf of the user client.
string
api_nameQueryThe unique API Name for the leaderboard. This is specified when you created the leaderboard.string
fieldsQueryRequired. A comma separated list of fields to retrieve. Possible values -
  • user {id, alias, profile_url}. Gets the id, profile name, and profile picture URL for the user.
  • rank - The entry's rank relative to the current filter. The top entry on the leaderboard has a rank of one
  • score - the entry's score.
  • display_score - the integer representing score that will be displayed to users.
  • timestamp - Unix time for when the entry was posted.
  • extra_data_base64 - The entry's app-supplied metadata, base64 encoded.
A comma-separated list of strings
filterQueryOptional. Indicates what type of filtering should be applied.Enum value. Valid values: FRIENDS, USER_IDS, NONE
start_atQueryOptional. Indicates the leaderboard position to start the retrieval.Enum value. Valid values: CENTERED_ON_VIEWER, CENTERED_ON_VIEWER_OR_TOP, TOP, OFFSET
offsetQueryRequired when the start-at value is offset and indicates the offset value to use.integer
summaryQueryOptional. True to indicate a summary should be provided, otherwise false.Boolean
limitQueryOptional. Indicates the number limit of entries to return.integer
user_idsQueryRequired when the filter value is USER_IDS. Specifies which users' entries to fetch.A comma-separated list of integers

Example Response:

{
    "data": [{
        "id": "1074233745529170",
        "user": {
            "id": "865307770207175",
            "alias": "UnknownXuid",
            "profile_url": "someUrl",
            "rank": 25,
            "score": 12345,
            "timestamp": 1456523020,
            "extra_data_base64": "T2N1bHVz"
        }
    }],
    "summary": {
        "total_count": 45
    },
    "paging": {
        "next": "...",
        "previous": "..."
    }
}



The first ID returned in the response above is the entry ID, which can be referenced and used to delete the user’s leaderboard entry.


Get All Leaderboards In An Application

Get all leaderboards in your application, including those that are not public facing.

https://graph.oculus.com/{app_id}/leaderboards

METHOD: GET

Example Request:

GET/1234757621998335/leaderboards/
HTTP/1.1
Host: graph.oculus.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

Example cURL Request:

$ curl -G -d "access_token=OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a" https://graph.oculus.com/2963766027051815/leaderboards

Parameters:

ParameterParam TypeDescriptionType
access_tokenHeaderRequired. A bearer token that contains one of the following:
  • App credentials - the app ID and app secret separated by the pipe symbol
  • User credentials - the user access token
Use the app credentials when making a request on behalf of the server, and the user credentials when you make a request on behalf of the user client.
string

Example Response:

{"data":[{"id":"3123283331082594"},{"id":"3063603433693729"},{"id":"3076319039125567"}]}

Delete a Single User’s Leaderboard Entry

Use this method to delete a single entry by specifying the entry-id. An entry-id is returned from the Retrieve Data about a User’s Leaderboard Entry request.

URL: https://graph.oculus.com/{entry_id}

METHOD: DELETE

Example Request:

DELETE /12345 HTTP/1.1
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

Example cURL request:

$ curl -X DELETE -d "OC1234757621998335f7a788b0c0b270f9691d0a06d5a5" ^
https://graph.oculus.com/12345

Parameters:

ParameterParam TypeDescriptionType
access_tokenHeaderRequired. A bearer token that contains one of the following:
  • App credentials - the app ID and app secret separated by the pipe symbol
  • User credentials - the user access token
Use the app credentials when making a request on behalf of the server, and the user credentials when you make a request on behalf of the user client.
string
entry_idPathRequired. Identifier for a particular entry in the leaderboard. You must retrieve this with a call to get all leaderboard entries. string

Example Response:

{"success":true}

Delete All Leaderboard Entries

Delete all of the entries in a leaderboard. This operation can not be reversed.

URL: https://graph.oculus.com/leaderboard_remove_all_entries

METHOD: POST

Example Request:

POST /leaderboard_remove_all_entries?api_name=MY_NEW_LEADERBOARD
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

Example cURL request:

$ curl -d "OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5" ^
-d "api_name=MY_NEW_LEADERBOARD" ^
https://graph.oculus.com/leaderboard_remove_all_entries

Parameters:

ParameterParam TypeDescriptionType
access_tokenHeaderRequired. A bearer token that contains one of the following:
  • App credentials - the app ID and app secret separated by the pipe symbol
  • User credentials - the user access token
Use the app credentials when making a request on behalf of the server, and the user credentials when you make a request on behalf of the user client.
string
api_nameQueryThe unique API Name for the leaderboard. This is specified when you created the leaderboard.string

Example Response:

{"success":true}

Delete a Leaderboard

Delete a leaderboard. The leaderboard-id is the ID returned from the Create or Update a Leaderboard request. Once deleted, a leaderboard entry cannot be recovered.

URL: https://graph.oculus.com/leaderboard_id

METHOD: DELETE

Example Request:

DELETE /12345567893
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5
$ curl -X "DELETE" ^
-d "access_token=OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5" ^
https://graph.oculus.com/12345567893

Parameters:

ParameterParam TypeDescriptionType
access_tokenHeaderRequired. A bearer token that contains one of the following:
  • App credentials - the app ID and app secret separated by the pipe symbol
  • User credentials - the user access token
Use the app credentials when making a request on behalf of the server, and the user credentials when you make a request on behalf of the user client.
string
leaderboard-idPathRequired. Numeric identifier for a leaderboard. You must retrieve this with a call to create or update a leaderboard. string

Example Response:

{"success":true}