API reference
OVR_Requests_Challenges.h File
The Challenges API enhances social interactions in your app, which use ovr_GroupPresence_SetDestination() to create shareable links for score- based competition. Players can repeatedly challenge others, get to know them, and compete asynchronously. Challenges can be ranked by highest/lowest scores within a time period. Leaderboard-integrated apps get Challenges for free, accessible through the Scoreboards UI. Players can create and invite others to Challenges via the Challenges app.
Functions
ovrRequest ovr_Challenges_Create
( const char * leaderboardName,
ovrChallengeOptionsHandle challengeOptions )
A message with type ovrMessage_Challenges_Create will be generated in response.First call ovr_Message_IsError() to check if an error occurred.If no error occurred, the message will contain a payload of type ovrChallengeHandle. Extract the payload from the message handle with ovr_Message_GetChallenge().
Parameters
DeprecatedleaderboardName
A string represents the name of the leaderboard.
challengeOptions
This indicates the options of the challenge and it can be retrieved by ovr_ChallengeOptions_Create().
Use server-to-server API call instead.
ovrRequest ovr_Challenges_DeclineInvite
( ovrID challengeID )
If the current user has the necessary permissions, they can decline a challenge by providing the challenge ID, which can be obtained using ovr_Challenge_GetID().
Parameters
A message with type ovrMessage_Challenges_DeclineInvite will be generated in response.First call ovr_Message_IsError() to check if an error occurred.If no error occurred, the message will contain a payload of type ovrChallengeHandle. Extract the payload from the message handle with ovr_Message_GetChallenge(). challengeID
The ID of challenge that the user is going to decline. It can be retrieved by ovr_Challenge_GetID().
ovrRequest ovr_Challenges_Delete
( ovrID challengeID )
A message with type ovrMessage_Challenges_Delete will be generated in response.First call ovr_Message_IsError() to check if an error occurred.This response has no payload. If no error occurred, the request was successful. Yay!
Parameters
DeprecatedchallengeID
The uuid of the challenge.
Use server-to-server API call instead.
ovrRequest ovr_Challenges_Get
( ovrID challengeID )
Gets detailed information for a single challenge by providing the challenge ID, which can be retrieved by calling ovr_Challenge_GetID().
Parameters
A message with type ovrMessage_Challenges_Get will be generated in response.First call ovr_Message_IsError() to check if an error occurred.If no error occurred, the message will contain a payload of type ovrChallengeHandle. Extract the payload from the message handle with ovr_Message_GetChallenge(). challengeID
The id of the challenge whose entries to return, which can be retrieved by calling ovr_Challenge_GetID().
ovrRequest ovr_Challenges_GetEntries
( ovrID challengeID,
int limit,
ovrLeaderboardFilterType filter,
ovrLeaderboardStartAt startAt )
Retrieves a list of entries for a specific challenge, with options to filter and limit the results. By providing the challengeID, you can specify which challenge's entries you want to retrieve. The limit parameter allows you to control the number of entries returned. The filter parameter enables you to refine the results to only include entries from users who are bidirectional followers. The startAt parameter allows you to define whether to center the query on the user or start at the top of the challenge.
Parameters
A message with type ovrMessage_Challenges_GetEntries will be generated in response.First call ovr_Message_IsError() to check if an error occurred.If no error occurred, the message will contain a payload of type ovrChallengeEntryArrayHandle. Extract the payload from the message handle with ovr_Message_GetChallengeEntryArray(). challengeID
The id of the challenge whose entries to return, which can be retrieved by calling ovr_Challenge_GetID().
limit
Sets a limit on the maximum number of challenges to be fetched, which can be useful for pagination or performance reasons.
filter
By using the ovrLeaderboardFilterType(), you can refine the results to only include entries from users who are bidirectional followers.
startAt
Defines whether to center the query on the user or start at the top of the challenge. If this is ovrLeaderboard_StartAtCenteredOnViewer() or ovrLeaderboard_
ovrRequest ovr_Challenges_GetEntriesAfterRank
( ovrID challengeID,
int limit,
unsigned long long afterRank )
Returns a list of entries for a specific challenge, starting from a specified rank. By providing the challengeID and rank, you can specify which challenge's entries you want to retrieve and where to start the query. The limit parameter allows you to control the number of entries returned.
Parameters
A message with type ovrMessage_challengeID
The id of the challenge whose entries to return, which can be retrieved by calling ovr_Challenge_GetID().
limit
Sets a limit on the maximum number of challenges to be fetched, which can be useful for pagination or performance reasons.
afterRank
The position after which to start. For example, 10 returns challenge results starting with the 11th user.
ovrRequest ovr_Challenges_GetEntriesByIds
( ovrID challengeID,
int limit,
ovrLeaderboardStartAt startAt,
ovrID * userIDs,
unsigned int userIDLength )
Retrieves a list of challenge entries for a specific set of user IDs, with options to filter and limit the results. This method is useful for retrieving a list of challenge entries for a specific set of users, allowing you to display their progress and rankings within the challenge.
Parameters
A message with type ovrMessage_Challenges_GetEntriesByIds will be generated in response.First call ovr_Message_IsError() to check if an error occurred.If no error occurred, the message will contain a payload of type ovrChallengeEntryArrayHandle. Extract the payload from the message handle with ovr_Message_GetChallengeEntryArray(). challengeID
The id of the challenge whose entries to return, which can be retrieved by calling ovr_Challenge_GetID().
limit
Sets a limit on the maximum number of challenges to be fetched, which can be useful for pagination or performance reasons.
startAt
Defines whether to center the query on the user or start at the top of the challenge. If this is ovrLeaderboard_StartAtCenteredOnViewer() or ovrLeaderboard_
userIDs
Defines a list of user ids to get entries for.
userIDLength
The number of user IDs provided.
ovrRequest ovr_Challenges_GetList
( ovrChallengeOptionsHandle challengeOptions,
int limit )
Returns a list of challenges that match the specified options. The ovr_ChallengeOptions_Create() parameter allows you to specify the criteria for the challenges you want to retrieve. The limit parameter allows you to control the number of challenges returned.
Parameters
A message with type ovrMessage_Challenges_GetList will be generated in response.First call ovr_Message_IsError() to check if an error occurred.If no error occurred, the message will contain a payload of type ovrChallengeArrayHandle. Extract the payload from the message handle with ovr_Message_GetChallengeArray(). challengeOptions
This indicates the options of the challenge and it can be retrieved by ovr_ChallengeOptions_Create().
limit
Sets a limit on the maximum number of challenges to be fetched, which can be useful for pagination or performance reasons.
ovrRequest ovr_Challenges_GetNextChallenges
( const ovrChallengeArrayHandle handle )
Requests the next block of challenges.
Parameters
A message with type ovrMessage_Challenges_GetNextChallenges will be generated in response.First call ovr_Message_IsError() to check if an error occurred.If no error occurred, the message will contain a payload of type ovrChallengeArrayHandle. Extract the payload from the message handle with ovr_Message_GetChallengeArray(). handle
The return value from ovr_Message_GetChallengeArray().
ovrRequest ovr_Challenges_GetNextEntries
( const ovrChallengeEntryArrayHandle handle )
Requests the next block of challenge entries.
Parameters
A message with type ovrMessage_Challenges_GetNextEntries will be generated in response.First call ovr_Message_IsError() to check if an error occurred.If no error occurred, the message will contain a payload of type ovrChallengeEntryArrayHandle. Extract the payload from the message handle with ovr_Message_GetChallengeEntryArray(). handle
The return value from ovr_Message_GetChallengeEntryArray().
ovrRequest ovr_Challenges_GetPreviousChallenges
( const ovrChallengeArrayHandle handle )
Requests the previous block of challenges.
Parameters
A message with type ovrMessage_handle
The return value from ovr_Message_GetChallengeArray().
ovrRequest ovr_Challenges_GetPreviousEntries
( const ovrChallengeEntryArrayHandle handle )
Requests the previous block of challenge entries.
Parameters
A message with type ovrMessage_Challenges_GetPreviousEntries will be generated in response.First call ovr_Message_IsError() to check if an error occurred.If no error occurred, the message will contain a payload of type ovrChallengeEntryArrayHandle. Extract the payload from the message handle with ovr_Message_GetChallengeEntryArray(). handle
The return value from ovr_Message_GetChallengeEntryArray().
ovrRequest ovr_Challenges_Join
( ovrID challengeID )
If the current user has the necessary permissions to join, participate in a challenge by providing the challenge ID, which can be retrieved using ovr_Challenge_GetID().
Parameters
A message with type ovrMessage_Challenges_Join will be generated in response.First call ovr_Message_IsError() to check if an error occurred.If no error occurred, the message will contain a payload of type ovrChallengeHandle. Extract the payload from the message handle with ovr_Message_GetChallenge(). challengeID
The ID of challenge that the user is going to join. It can be retrieved by ovr_Challenge_GetID().
ovrRequest ovr_Challenges_Leave
( ovrID challengeID )
If the current user has the necessary permissions, they can leave a challenge by providing the challenge ID, which can be obtained using ovr_Challenge_GetID().
Parameters
A message with type ovrMessage_Challenges_Leave will be generated in response.First call ovr_Message_IsError() to check if an error occurred.If no error occurred, the message will contain a payload of type ovrChallengeHandle. Extract the payload from the message handle with ovr_Message_GetChallenge(). challengeID
The ID of challenge that the user is going to leave. It can be retrieved by ovr_Challenge_GetID().
ovrRequest ovr_Challenges_UpdateInfo
( ovrID challengeID,
ovrChallengeOptionsHandle challengeOptions )
A message with type ovrMessage_Challenges_UpdateInfo will be generated in response.First call ovr_Message_IsError() to check if an error occurred.If no error occurred, the message will contain a payload of type ovrChallengeHandle. Extract the payload from the message handle with ovr_Message_GetChallenge().
Parameters
DeprecatedchallengeID
The uuid of the challenge.
challengeOptions
This indicates the options of the challenge and it can be retrieved by ovr_ChallengeOptions_Create().
Use server-to-server API call instead.
Did you find this page helpful?
Virtual reality / Meta Horizon
Support and legal
Virtual reality / Meta Horizon
Support and legal
Virtual reality / Meta Horizon
Support and legal
English (US)
© 2025 Meta