Retrieve a leaderboard by request name

post https://us-central1-readysandbox.cloudfunctions.net/leaderboardV2-getByRequestName

Responses

Response body

object

string

Unique id of the leaderboard.

appIds

array of strings

required

List of application ids where this leaderboard is used.

appIds*

requestName

string

required

Leaderboard request name. This value can be used to query leaderboards.

tags

name

string

required

Leaderboard name. Is also used to store localization key for the name.

description

string

required

Leaderboard description. Is also used to store localization key for the description.

setBy

string

required

Defines who can set/add scores to the leaderboard:

client - the client and the server can set/add scores to the leaderboard.
server - only the server can set/add scores to the leaderboard.

client server

invertSortOrder

boolean

required

Sorting direction. False for descending order, true for ascending order.

decimalOffset

integer

required

Determines how many digits of the score are displayed after the decimal point.

type

string

Defaults to numeric

The leaderboard type that determines the results unit. Default is 'numeric'.
Possible values:

time - the leaderboard is time-based.
numeric - the leaderboard is numeric-based.

time numeric

rewardsAtReset

array of objects

Rewards which will be earned at reset period.

rewardsAtReset

object

placeFrom

integer

required

The place from which users will earn the reward.

placeTo

integer

required

The place up to which users will earn the reward.

achievementId

string

required

Specifies the reward or achievement, which may contain virtual items, currency rewards, etc.

rewardsDrawType

string

The leaderboard rewards draw type that determines how the leaderboard should draw rewards, possible values:

placeBased - rewards will be drawn accordingly users places.
scoreBased - rewards will be drawn randomly, but users with higher score will have more chance to win.
scoreBasedOnePerUser - same as the scoreBased, but with limitation for one reward at whole leaderboard per one user.
scoreBasedOnePerUserAndReward - same as the scoreBased, but with limitation for one unique reward per one user
but different rewards could be added to same user.

placeBased scoreBased scoreBasedOnePerUser scoreBasedOnePerUserAndReward

createdAt

int64

Date and time when the leaderboard was created in milliseconds since Jan 1, 1970 UTC. Automatically populated by the backend.

updatedAt

int64

Date and time when the leaderboard was last updated in milliseconds since Jan 1, 1970 UTC. Automatically populated by the backend.

createdBy

string

User Id who created the leaderboard. This field is automatically populated by the backend.

updatedBy

string

User Id who last time updated the leaderboard. This field is automatically populated by the backend.

time

object

required

The time when the leaderboard is available.

hasStart

boolean

Indicates whether a start time is specified. Is populated by the type-safe clients if there is no way to leave a property undefined.

start

int64

The start time in milliseconds since midnight, January 1, 1970 UTC. This field is relevant only if hasStart is not false.

hasEnd

boolean

Indicates whether an end time is specified. Is populated by the type-safe clients if there is no way to leave a property undefined.

end

int64

The end time in milliseconds since midnight, January 1, 1970 UTC. This field is relevant only if hasEnd is not false.

hasInterval

boolean

Indicates whether an interval is specified. Is populated by the type-safe clients if there is no way to leave a property undefined.

intervalDuration

int64

The interval duration in milliseconds. This field is relevant only if hasInterval is not false.

intervalDelay

int64

The interval delay in milliseconds. This field is relevant only if hasInterval is not false.

hasPromo

boolean

Indicates whether a promo is specified. Is populated by the type-safe clients if there is no way to leave a property undefined.

promo

int64

The promo time in milliseconds before the start time. This field is relevant only if hasPromo and hasStart are not false.

hasGrace

boolean

Indicates whether a grace period is specified. Is populated by the type-safe clients if there is no way to leave a property undefined.

grace

int64

The grace period in milliseconds after the end time. This field is relevant only if hasGrace and hasEnd are not false.

requiredToJoin

object

Join leaderboard requirements. To setScore and addScore to the leaderboard.

operation

string

The operation to be performed on the requirement.
Available operations are:

and - the user must meet all of the requirements.
or - the user must meet at least one of the requirements.
not - the user must not meet the requirement.

and or not

requirements

array of objects

The list of requirements.

requirements

object

type

string

required

gamepass_by_id
gamepass_by_request_name
item_by_id
item_by_tag
achievement_by_id
achievement_by_request_name
social_connected
discord_joined_server
discord_has_role
twitter_retweeted
twitter_liked
twitter_replied

Specifies the type of the requirement.
Available types are:

gamepass_by_id - the user needs to have a gamepass with a specific id to join a leaderboard, purchase a
store offer or complete an achievement.
gamepass_by_request_name - the user needs to have a gamepass with a specific request name to join a
leaderboard, purchase a store offer or complete an achievement.
item_by_id - the user needs to have a virtual item with a specific id to join a leaderboard, purchase a
store offer or complete an achievement.
item_by_tag - the user needs to have a virtual item with a specific tag to join a leaderboard, purchase a
store offer or complete an achievement.
achievement_by_id - the user needs to complete an achievement to join a leaderboard, purchase a store
offer or complete an achievement.
achievement_by_request_name - the user needs to complete an achievement with a specific request name to
join a leaderboard, purchase a store offer or complete an achievement.
social_connected - the user needs to connect their social account to join a leaderboard, purchase a store
offer or complete an achievement. The 'id' field is the social network id: 'discord' or 'twitter'.
discord_joined_server - the user needs to join a specific Discord server to join a leaderboard, purchase a
store offer or complete an achievement.
discord_has_role - the user needs to have a specific role in a Discord server to join a leaderboard,
purchase a store offer or complete an achievement.
twitter_retweeted - the user needs to retweet a specific tweet to join a leaderboard, purchase a store
offer or complete an achievement.
twitter_liked - the user needs to like a specific tweet to join a leaderboard, purchase a store offer or
complete an achievement.
twitter_replied - the user needs to reply to a specific tweet to join a leaderboard, purchase a store offer
or complete an achievement.

gamepass_by_id gamepass_by_request_name item_by_id item_by_tag achievement_by_id achievement_by_request_name social_connected discord_joined_server discord_has_role twitter_retweeted twitter_liked twitter_replied

string

required

The id field is used to provide the data: - gamepass_by_id - the 'id' is the gamepass id. - gamepass_by_request_name - the 'id' is the gamepass request name. - item_by_id - the 'id' is the virtual item id. - item_by_tag - the 'id' is the virtual item tag. - achievement_by_id - the 'id' is the achievement id. - achievement_by_request_name - the 'id' is the achievement request name. - discord_joined_server - the 'id' is the Discord server/guild id. - discord_has_role - the 'id' is the Discord server/guild id. Additionaly 'payload' parameter is excpected for

the Discord role id.

twitter_retweeted - the 'id' is the tweet id. - twitter_liked - the 'id' is the tweet id. - twitter_replied - the 'id' is the tweet id.

autoClaim

boolean

Indicates whether the leaderboard rewards are automatically claimed by the user. If false, the rewards must be claimed manually. The time.end is required and optionally time.grace to be set if autoClaim is true.

participationFees

array of objects

List of participation fees for the leaderboard.
The fees are deducted when the user sets or adds a score to the leaderboard for the first time.

participationFees

object

type

string

required

Specifies the type of the participation fee.
Available types are:

currency - the user needs to pay a specific amount of currency to join a leaderboard.
gamepass_by_id - the user needs to have a gamepass with a specific id to join a leaderboard.
gamepass_by_request_name - the user needs to have a gamepass with a specific request name to join a
leaderboard.

currency gamepass_by_id gamepass_by_request_name

string

required

The id of the entity to check in user data. For example, if the type is gamepass_by_id, the id is the id of the gamepass. If the type is gamepass_by_request_name, the id is the request name of the gamepass.

quantity

integer

≥ 1

The quantity of the entity to check in user data. For example, if the type is currency, the quantity is the amount of currency. If the type is gamepass_by_id, the quantity is the quantity of the game passes the user needs to have.

participationRewards

array of strings

List of achievement ids that are triggered for the first score set or added to the leaderboard.

participationRewards

scoreMultipliers

object

List of score multipliers for the leaderboard.

rounding

string

required

The rounding method to apply after calculating the final score multiplier.

floor ceil round

multipliers

array of objects

required

A list of individual score multipliers, each with a condition and an optional group association.

multipliers*

object

condition

object

required

multiplier

float

required

The numerical multiplier applied when the condition is met.

group

string

The Id of the group this multiplier belongs to.

groups

array of objects

A list of multiplier groups that define aggregation rules for multipliers.

groups

object

string

required

The unique string identifier for the group. Multipliers reference this Id to be aggregated together.

aggregation

string

required

The aggregation method used to combine multipliers within the group. Available options: 'sum' - adds all multipliers together, 'max' - takes the highest multiplier in the group, 'avg' - calculates the average of all multipliers, 'mul' - multiplies all multipliers together.

sum max avg mul

cap

number

An optional upper limit for the final aggregated multiplier in the group.

fakeEntries

object

Fake entries for the leaderboard.

populateOnCreate

boolean

Indicates whether to populate fake entries on creation.

populateOnReset

boolean

Indicates whether to populate fake entries on reset.

predefinedEntries

array of numbers

An array of predefined entries to use as fake data.

predefinedEntries

generationRules

object

required

Rules for generating fake entries.

filterEntriesWithZeroScore

boolean

Indicates whether the leaderboard entries with zero score should be filtered out. If true, the entries with zero score are not displayed in the leaderboard.

400

Invalid arguments. Either 'appId' or 'requestName' is missing or not a string.

410

Leaderboard not found with the provided 'appId' and 'requestName'.

Language

URL


xxxxxxxxxx
1
curl --request POST \
2
     --url https://us-central1-readysandbox.cloudfunctions.net/leaderboardV2-getByRequestName \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json'


xxxxxxxxxx
102
}
1
{
2
  "id": "string",
3
  "appIds": [
4
    "string"
5
  ],
6
  "requestName": "string",
7
  "tags": [
8
    "string"
9
  ],
10
  "name": "string",
11
  "description": "string",
12
  "setBy": "client",
13
  "invertSortOrder": true,
14
  "decimalOffset": 0,
15
  "type": "numeric",
16
  "rewardsAtReset": [
17
    {
18
      "placeFrom": 0,
19
      "placeTo": 0,
20
      "achievementId": "string"
21
    }
22
  ],
23
  "rewardsDrawType": "placeBased",
24
  "createdAt": 0,
25
  "updatedAt": 0,

200Leaderboard successfully retrieved.