Tournaments

Tournaments are a great way to engage your community, get player feedback, and get wider visibility for your game. We regularly host tournaments, and also help organize Twitch streams of your game. To run a tournament with us, please reach out at developers@fractal.is.

Scores

A Score represents a game event of some type 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 an summed aggregation of all their scores.

{
  "user_id": "user123",
  "external_user_id": "player1234",
  "type": "kills",
  "value": "1"
}

Attributes

user_id	A valid Fractal Wallet user. We'll validate this user_id to our internal users to create the score and be able to show a username on leaderboards, etc.
external_user_id	(optional) Represents your internal user id. Scores are indexed on (user_id, external_user_id). Scores with different pairs are part of a different set of scores.
type	A valid score type that we've agreed on beforehand. The type is used to populate user-facing UIs such as leaderboards, by capitalising first letters and replacing underscores with spaces. For example, "kills" becomes "Kills" and "whitelist_token" type becomes "Whitelist Tokens". When a score is sent with an invalid type, it is ignored for such UI elements.
value	Represents the score value that gets aggregated. If 2 scores with "type": "kills" and "value": "1" are sent for the same user, this user now has 2 kills recorded.

Create a Score

To create a score, send a POST request to the scores API endpoint for your tournament with the scores parameters previously shown. If your score creation succeeded, you should receive a response with a 200 status code.

To access this endpoint, your server needs to be authenticated.

💡

To generate your Project auth token check out Server Auth Guide

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": "your_user_id"
}
'

Get Latest Scores

To query the 10 latest created scores, send a GET request to the scores API endpoint. You can optionally add an "offset" parameter.

curl --request GET \
     --url 'https://api.fractal.is/sdk/v1/tournament/<tournament_id>/scores' \
     --header 'Authorization: Bearer <project_auth_token>' \
     --header 'accept: application/json'

The response body will have a list of Scores and an optional "next" parameter, representing the next offset, if available.

{
  "scores": [{...}, {...}],
  "next": "10",
}

Get a tournament's leaderboard

Once scores have been created, a tournament will get its leaderboard populated, with players ordered by the score type set during the tournament's creation. Below is an example response.

To query the leaderboard, send a GET request to the leaderboard API endpoint. You can optionally add a "limit" and "offset" parameter.

curl --request GET \
     --url 'https://api.fractal.is/sdk/v1/tournament/<tournament_id>/leaderboard?leaderboardType=UNKNOWN&orderDirection=DESC' \
     --header 'Authorization: Bearer <project_auth_token>' \
     --header 'accept: application/json'

The response body will be the following leaderboard object:

{
  "scoreTypes": ["deaths", "kills"],
  "ranks": [
    {
      "userId": "123",
      "externalUserId": "456",
      "scores": [
        {
          "scoreType": "deaths",
          "total": 2
        },
        {
          "scoreType": "kills",
          "total": 3
        }
      ]
    },
    {
      "userId": "321",
      "externalUserId": "456",
      "scores": [
        {
          "scoreType": "deaths",
          "total": 1
        },
        {
          "scoreType": "kills",
          "total": 1
        }
      ]
    }
  ]
}

Tournament Guidelines React