Overview

Leaderboard Service provides endpoints to create/modify/update leaderboards.

There are 2 main components to the leaderboard service, a leaderboard configuration, and user scores.

The configurations defined how a leaderboard ingests data, while the user scores will tell the leaderboard what scores to insert/update

Configurations

The configurations of a leaderboard is currently set via JSON, the dev-portal UI is in the works.

The config has the following basic attributes:

• name - The name of the leaderboard, this is used to reference a specific leaderboard when loading/retrieving data
• order - One of either ascending or descending, determines if the ranks should be returned as highest score first (descending) or lowest score first (ascending)
• data - an arbitrary string that can be used to contain additional information about the leaderboard. This can be a single value, a json, etc... if you want to use binary data, you need to base64 the data.

and the following more complex attributes:

• timeframes - determines the timeframes for which we record scores, you can specify multiple timeframes you want to record. Possible options are: "all", "manual", "yearly", "monthly", "weekly", "daily"
• score_config - configuration determining how scores are accumulated in the leaderboard

For more details on the complex attributes, see the corresponding subsections below

Timeframes

The timeframes are defined as follows:

• all - a timeframe that includes the accumulated scores since the leaderboard was created. The configuration value is a boolean, where true means that the all leaderboard is enabled, and false means that it is disabled
• manual - a timeframe that allows the user to manually set their leaderboard intervals. Configuration looks like the following:

"manual": {
            "retention": 0,
            "archive": true,
            "start_dates": [1494500000, 1494530000, 1494560000]
        }

• yearly, monthly, weekly, daily - a timeframe that will automatically rotate scores based on the incomming timestamp. Configuration looks like the following:

"<inteval name>": {
            "retention": 0,
            "archive": true,
            "rotation_trigger": "1494505756"
        },

Note: You can omit any of the above to not generate a leaderboard for the corresponding timeframe.

For the timeframe configurations besides all a retention and archive attribute is required. These attributes determine how many leaderboards to store for lookup (retention), and the archive attribute determines if the removed leaderboards should be archived for historic purposes.

The attribute start_dates is specific to the manual leaderboard, and is a list of unix timestamps (in seconds from UTC epoch), each representing a new leaderboard start time. These times will be sorted from largest to smallest, and determine where scores are loaded. Smaller timestamps will act as a starting timestamp, while larger timestamps will act as an ending timestamp (non-inclusive). All scores loaded with a timestamp smaller than the smallest timestamp will be dropped, while all scores loaded with a timestamp greater than the largest timestamp will belong to the largest timestamp.

The following table shows which leaderboard scores are loaded in, assuming a start_dates configuration of [1494500000, 1494530000, 1494560000]:

Using the above table, a score loaded with a timestamp of 1494521521 is between 1494500000 and 1494529999, and thus belongs to the 1494500000 leaderboard

The attribute rotation_trigger is a UNIX timestamp (in seconds from UTC epoch), this timestamp is used to determine when to rollover the yearly/monthly/weekly/daily timeframes.

The following table shows what values from the rotation trigger are used to deliniate a new leaderboard:

Using the above table, a rotation_trigger of 1494521521 (Thursday, 2017-05-11T16:52:01Z) will rotate leaderboards every:

• Year on May 5th 16:52 (UTC)
• Month on the 5th at 16:52 (UTC)
• Weekly on Thursday at 16:52 (UTC)
• Daily at 16:52 (UTC)

Note: As a special case for monthly rotations, if you specify a rotation trigger on a day > 28th of the month, then the rollover will be either the day of the month, if it exists, or the highest day of that month. For example, if you specify a rotation trigger of November 30th, then on the month of Feburary, the rotation will be on the 28/29th, and on March, it will rotation on the 31st instead.

Score configs

The score configs determine how new scores are added to the leaderboard(s). The configuration looks like the following:

"score_config": {
        "type": "insert",
        "capacity": 500,
        "has_data": true
    },

Where:

• type - one of:
  • insertonly - processing user scores will always insert a new record, this can be used for a "high score" leaderboard, if set, "capacity" must also be defined. Note: you must provide unique id's for every entry you want to be added to the leaderboard. If a previous entry already has the assigned id, then the score will NOT be recorded
  • increment - processing user scores will accumulate the user score if it already exists, or create a new record with the value if it doesn't
  • highscore - only updates scores that are higher than the previously registered score
  • lowscore - only updates the scores that are lower than the previously registered lowest score
• capacity - integer representing the number of scores to keep for this leaderboard (only applicable for type "insertonly")
• has_data - true/false, if true, then you can send an additional "data" field with each score that you send to the database. This data field will be overwritten on subsequent updates to the score, and when the leaderboard is retrieved, the data will also be sent back with it.

Example leaderboard configuration

The following is an example of the complete configuration for a leaderboard

{
    "name": "high_score",
    "order": "descending",
    "timeframes": {
        "all": true/false,
        "manual": {
            "retention": 0,
            "archive": true,
            "start_dates": [1494500000, 1494530000, 1494560000]
        }
        "yearly": {
            "retention": 0,
            "archive": true,
            "rotation_trigger": "1494505756"
        },
        "monthly": {
            "retention": 4,
            "archive": true,
            "rotation_trigger": "1494505756"
        },
        "weekly": {
            "retention": 14,
            "archive": true,
            "rotation_trigger": "1494505756"
        },
        "daily": {
            "retention": 7,
            "archive": false,
            "rotation_trigger": "1494505756"
        },
    },
    "score_config": {
        "type": "insert",
        "capacity": 500,
        "has_data": true
    },
    "data": "display_name=\"Trivia Leaderboard\" other_property=\"other_value\""
}

User scores

Loading user scores takes the following general format:

"scores": [
    {
      "member": "11",
      "score": 1,
      "data":  "only if data is enabled in the score config"
    }
]

• member - will generally represent the id of the user this score belongs to, but can also be a reference value, this must be the case if the score type is "insertonly".
• score - The score you want to add to the leaderboard(s)
• data - an optional field that will accompany the individual score to give additional context about about the record