Note: You are viewing the Unity version of this topic. To view this topic for native development, see Achievements (Native). To view this topic for Unreal development, see Achievements (Unreal).
Create trophies, badges, awards, and more to challenge your users to reach a goal or objective. Users can see the achievements their friends have earned creating a competition among friends. Achievements earned in your app can also be displayed in Oculus Home to show a user’s progress in and progression through a game. This guide shows you how to define global achievements, the SDK methods and Server-to-Server calls you can make to interact with the achievements service, and an example Unity implementation you can review. The Oculus Platform supports three types of achievements: simple, count and bitfield. Each achievement type has a different unlock mechanism.
The Oculus Platform tracks and manages achievements. The platform displays a toast notification and plays a sound when an achievement is unlocked. Your app manages the triggers and updates for achievements and displays achievements to the user.
Note that this feature accesses user data and may require you to complete the Data Use Checkup form prior to submitting your app to the Oculus Store. For more information, see Complete a Data Use Checkup.
The first step in adding achievements to your game is to define the achievements and how they are unlocked. To create an achievement, navigate to the Developer Dashboard> Platform Services > Achievements. When you create achievements, you can choose to localize the achievement into multiple languages. When entering the achievement information, select Choose Languages, check the boxes of the languages you would like to localize into, and enter the information for the languages selected. The language displayed to the user is based on the locale set for the user’s device OS.
Select Create Achievement and enter the following information:
Select Submit when you’re finished to save the achievement. You can update your achievements in the Developer Dashboard at any time. Archiving Achievements You can archive achievements at any time. Archiving does not delete the achievement or a user’s progress, it hides the achievement and any progress the user. You can unarchive an achievement to restore visibility to users.
Once you’re finished creating the achievements, you can integrate them in your game. When you call the functions in this section, make sure to use the achievement name you specified on the developer dashboard.
The following SDK methods can be called from your client app. Detail about each function can be found in the OVR_Requests_Achievements.h documentation in the Platform SDK Reference Content.
Task Description | Function |
---|---|
Retrieve information about a specific achievement including achievement name, type, and target or bitfield length. | Platform.Achievements.GetDefinitionsByName() |
Retrieve information about a user’s progress on a specific achievement; including, name, unlocked status, time the achievement was unlocked, current bitfield, and current count. | Platform.Achievements.GetProgressByName() |
Retrieves information about all achievements; including achievement name, type, and target or bitfield length. | Platform.Achievements.GetAllDefinitions() |
Retrieves information about a user’s progress on all achievements; including, name, unlocked status, time the achievement was unlocked, current bitfield, and current count. | Platform.Achievements.GetAllProgress() |
The following SDK methods can be called for any achievement that has a Client Authoritative write policy. If the achievement is Server Authoritative you’ll need to use the S2S REST calls in the section below to make updates from your trusted server.
Task Description | Function |
---|---|
Unlock a specified achievement. This will completely unlock an achievement, including count and bitfield achievements, even if the target has not been met. | Platform.Achievements.Unlock() |
Increment the count on a Count achievement. | Platform.Achievements.AddCount() |
Unlock a bit in a Bitfield type achievement. Once a bit is unlocked it will not change from that state. For example, if the bitfield is 10011 and you call AddFields passing 00110, the resulting state is 10111. | Platform.Achievements.AddFields() |
The following Unity example demonstrates setting an achievement to unlock on an event that you define. The following example is taken from the VRHoops sample app. Find the sample in the Oculus Integration Package for Unity. For more information, see Sample Apps.
The example first defines an achievement that was configured on the Developer Dashboard called LIKES_TO_WIN. The example then checks for an update message to see if the achievement has been unlocked and, if true, sets the achievement as unlocked in the app. Otherwise, the game moves on and increments the count on the achievement if a game condition is met, in this example if a win is recorded.
using UnityEngine; using System.Collections; using Oculus.Platform; using Oculus.Platform.Models; public class AchievementsManager : MonoBehaviour { // API NAME defined on the dashboard for the achievement private const string LIKES_TO_WIOptional= "LIKES_TO_WIN"; // true if the local user hit the achievement Count setup on the dashboard private bool m_likesToWinUnlocked; public bool LikesToWin { get { return m_likesToWinUnlocked; } } public void CheckForAchievmentUpdates() { Achievements.GetProgressByName(new string[]{ LIKES_TO_WIOptional}).OnComplete( (Message<AchievementProgressList> msg) => { foreach (var achievement in msg.Data) { if (achievement.Name == LIKES_TO_WIN) { m_likesToWinUnlocked = achievement.IsUnlocked; } } } ); } public void RecordWinForLocalUser() { Achievements.AddCount(LIKES_TO_WIN, 1); CheckForAchievmentUpdates(); } }
If you set an achievement to Server Authoritative, you’ll need to make API calls from your trusted server to the Oculus service to increment and unlock achievements. See the Server-to-Server Basics page for information about interacting with the Oculus REST APIs.
Use to create a new achievement or update an achievement that already exists. This will update the achievement for all users.
Request method/URL:
POST https://graph.oculus.com/$APPID/achievement_definitions
Parameters:
Parameter | Required/Optional | Description | Type | Example |
---|---|---|---|---|
access_token | Required | Bearer token that contains OC|$APP_ID |$APP_SECRET | string | “Bearer OC|1234|456789” |
api_name | Required | The name used to reference to the achievement in this API and in the client SDK. This alphanumeric string must be unique for the app. If the achievement exists, the call will update it. If it doesn’t exist, the call will create an achievement with this name. | string | “VISIT_3_CONTINENTS” |
achievement_type | Required | This is the achievement type. There are three types of achievement, please see the description above for information on the different types. | enum with values: simple, count, bitfield | “simple” |
entry_write_policy | Required | Determines who is allowed to write achievement progress. Please see the description above for information on the two different write policies. | enum with values: client_ authoritative, server_ authoritative | “client_authoritative” |
target | Required if achievement_type is count or bitfield | The number of event occurrences for the achievement to be unlocked. Please see the description above for more information on target. | integer | 50 |
bitfield_length | Required if achievement_type = bitfield | The size of the bitfield for this achievement. | integer | 7 |
is_archived | Optional. Default is false. | Boolean that indicates if the achievement is archived. Can also be used to unarchive an achievement. Archiving does not delete the achievement or user progress. | boolean | “false” |
title | Required | The name of the achievement that the user sees. | string | “Visited 3 Continents” |
description | Required | The text description that the user sees. | string | “This achievement unlocks when...” |
unlocked_description _override | Optional | The text description that the user sees when the achievement is unlocked. | string | “Congratulations! You visited 3 continents.” |
is_secret | Optional - Default is false. | Boolean that indicates whether the achievement is hidden until earned. | boolean | “false” |
unlocked_image_file | Optional - A default image is used. | The local path to the icon shown after the achievement has been earned. Must be a 256x256 PNG file. | string | ”@/path/to/unlocked_icon.png; type=image/png” |
locked_image_file | Optional - If an unlocked image is provided, a grayscale version will be used as the locked image. Otherwise, a default is used. | The local path to the icon shown before the achievement is earned. Must be a 256x256 PNG file. | string | ”@/path/to/locked_icon.png; type=image/png” |
Example Create/Update Request
$ curl -F "access_token=Bearer OC|$APP_ID|$APP_SECRET" -F "api_name=VISIT_3_CONTINENTS" -F "achievement_type=BITFIELD" -F "achievement_write_policy=CLIENT_AUTHORITATIVE"-F "target=3" -F "bitfield_length=7" -F "is_archived=false" -F "title=Achievement Title" -F "description=How to earn me" -F "unlocked_description_override=You did it" -F "is_secret=false" -F "locked_image_file=@/path/to/locked_icon.png;type=image/png" -F "unlocked_image_file=@/path/to/unlocked_icon.png;type=image/png" https://graph.oculus.com/$APPID/achievement_definitions
Example Response
{"id":"1074233745960170"}
Query achievement definitions allows you to get information about achievements to display to your users.
Request method/URL:
GET https://graph.oculus.com/$APPID/achievement_definitions
Parameters:
Parameter | Required/Optional | Description | Type | Example |
---|---|---|---|---|
access_token | Required | Bearer token that contains OC|$APP_ID |$APP_SECRET | string | “Bearer OC|1234|456789” |
api_names | Optional | The names of the achievement definitions to fetch. If omitted all achievement definitions are returned. | string array | [“VISIT_3_CONTINENTS”, “WALK_500_MILES”] |
include_archived | Optional | Boolean that indicates whether to include archived achievements. This may only be used when an App Access Token is used to authenticate. | boolean | “false” |
fields | Optional | A comma-separated list of field names to retrieve. Can contain: api_name , achievement_type , achievement_write_policy , target , bitfield_length , is_archived , title , description , unlocked_description_override , is_secret , locked_image_uri , unlocked_image_uri . If omitted, only the IDs are returned. | String | “api_name,achievement_type” |
The field definitions are the same as in the create or update API call above. Server image URIs are provided instead of local file locations.
Example Request
$ curl -G -d "access_token=OC$APP_ACCESSTOKEN|$USER_ACCESSTOKEN" -d 'api_names=["VISIT_3_CONTINENTS", "WALK_500_MILES"]' -d "include_archived=true" -d 'fields=api_name,achievement_type,achievement_write_policy,target,bitfield_length,is_archived,title, description,unlocked_description_override,is_secret,locked_image_uri,unlocked_image_uri' https://graph.oculus.com/$APPID/achievement_definitions
Example Response
{ "data": [{ "id": "1074233745960170", "api_name": "VISIT_3_CONTINENTS", "achievement_type": "BITFIELD", "achievement_write_policy": "CLIENT_AUTHORITATIVE", "target": 3, "bitfield_length": 7, "is_archived": false, "title": "Achievement Title", "description": "How to earn me", "unlocked_description_override": "You did it", "is_secret": false, "locked_image_uri": "https://scontent.oculuscdn.com/...", "unlocked_image_uri": "https://scontent.oculuscdn.com/..." }, {...}] }
Write achievement progress updates a user’s progress on an achievement. This method accumulates progress, for count type achievements, instead of overwriting values. For example, add_count=25 will increment the count by 25, not set the current count to 25. This is so that conflicts that arise from updating achievements from multiple sources simultaneously or making progress from multiple devices in offline mode can be handled gracefully.
Request Method/URL:
POST https://graph.oculus.com/$USERID/achievements
Parameters:
Parameter | Required/Optional | Description | Type | Example |
---|---|---|---|---|
access_token | Required | Bearer token that contains OC|$APP_ID |$APP_SECRET | string | “Bearer OC|1234|456789” |
api_name | Required | The names of the achievement to update. | string | “VISIT_3_CONTINENTS” |
add_count | Required if the achievement is a Count type. | Value to add to the progress counter for this achievement. Only valid for COUNT achievements. | integer | 25 |
add_bits | Required if the achievement is a Bitfield type. | Bits to add to the progress of this achievement. Only valid for BITFIELD achievements. | string | “110001” |
force_unlock | Optional - Default is false. | Instantly unlocks an achievement regardless of progress. This must be used to unlock SIMPLE achievements. | boolean | “false” |
Example Request
$ curl -d "access_token=$APP_ACCESSTOKEN|$USER_ACCESSTOKEN" -d "api_name=MY_ACHIEVEMENT"-d "add_bits=0011001" -d "add_count=25" -d "force_unlock=true" https://graph.oculus.com/$USERID/achievements
Example Response
{"id":"1074233745960170","api_name":"MY_ACHIEVEMENT","just_unlocked":true}
The response will contain the parameter just_unlocked that indicates if this operation caused the achievement to unlock.
Retrieve a user’s progress for an achievement.
Request method/URI:
GET https://graph.oculus.com/$USERID/achievements
Parameters:
Parameter | Required/Optional | Description | Type | Example |
---|---|---|---|---|
access_token | Required | Bearer token that contains OC|$APP_ID |$APP_SECRET | string | “Bearer OC|1234|456789” |
api_names | Optional | The names of the achievement definitions to fetch. If omitted all achievement definitions are returned. | string array | [“VISIT_3_CONTINENTS”, “WALK_500_MILES”] |
Example Request
The definitions for the ‘fields’ are the same as in the Create or Update Achievement call above.
$ curl -G -d "access_token=$APP_ACCESSTOKEN|$USER_ACCESSTOKEN" -d 'api_names=["VISIT_3_CONTINENTS", "WALK_500_MILES"]' -d'fields'='definition{api_name,target},count_progress,bitfield_progress,is_unlocked,unlock_time' https://graph.oculus.com/$USERID/achievements
Example Response
{ "data": [{ "id": "1074233745960170", "definition": { "api_name": "VISIT_3_CONTINENTS", "target": 3 }, "count_progress": 0, "bitfield_progress": "1001100", "is_unlocked": true, "unlock_time": 1459815726 }] }
This method will remove all achievement progress, both locked and unlocked, for a user.
Request method/URI:
POST https://graph.oculus.com/achievement_remove_all
Parameters:
Parameter | Required/Optional | Description | Type | Example |
---|---|---|---|---|
access_token | Required | Bearer token that contains OC|$APP_ID |$APP_SECRET | string | “Bearer OC|1234|456789” |
user_id | Required | The user ID to remove the achievements for. | string | “12345” |
Example Request
$ curl -d "access_token=$APP_ACCESSTOKEN" -d "user_id=$USERID" https://graph.oculus.com/achievement_remove_all
Example Response
{"success":true}