Posting Scores

A Score represents a game event and value linked to a player. It can be a kill, an achievement, or anything else. A leaderboard can then be generated by either showing a user's high score, or a summed aggregation of all their scores.

Post Score

💡

Requires project API authentication. Always 'proxy' the request from the game client through a server you control. This is to prevent users from spoofing scores.

To create a new score entry, send a request to /sdk/tournament/score (opens in a new tab) POSTendpoint. Requests require a valid API authentication token to be passed in the Authorization header, and body should contain a JSON object that represents a scoring event with the following attributes:

{
   "score" : {
      "userId" : "some-fractal-user-id",
      "externalUserId" : "some-internal-id",
      "metadata" : {
         "format" : "king_of_the_hill",
         "matchId" : "some-match-id",
         "opponent" : "some-other-user-id",
         "team" : "blue",
         "player_ip_addr_hash": "Jd8HASdjf71jsdHh77ah126fjalal"
      },
      "type" : "pvp_win",
      "value" : 1
   }
}

💡

The tournamentId is optional, only include this id if you already have a tournament created by the Fractal team. Using a tournament id that doesn't exist will result in a 404 error.

Attributes

Atribute	Content
`score`	A instance of the score object (see below).
`tournamentId`	(optional) Unique tournament identificator.

Score object

Atribute	Content
`userId`	A valid Fractal Account user id.
`externalUserId`	(optional) Represents your internal user id.
`metadata`	(optional) A JSON object that represents additional information about the score.
`type`	A valid score type that we've agreed on beforehand. For example: `kills`, `points`. Multiple score types can be posted in separate requests.
`value`	Represents the score value that gets aggregated.

You can use the optional metadata field to store information such as the match id, the opponent, the team, the game mode, etc. This additional metadata can be used to produce more in-depth statistics but also find cheaters.

Example

curl --request POST \
    --url 'https://api.fractal.is/sdk/v1/tournament/<TOURNAMENT_ID>/score' \
    --header 'Authorization: Bearer <PROJECT_AUTH_TOKEN>' \
    --header 'accept: application/json' \
    --header 'content-type: application/json' \
    --data '{
    "userId": "<USER_ID>",
    "type": "type",
    "value": 100,
    "externalUserId": "<EXTERNAL_USER_ID>"
    }'

Overview Fetching Scores