Leveling Service

Leveling Schemas define a line of progression that users can make progress along to encourage engagement and reward participation or achievement.

URI: /leveling

Service Endpoints/Models: Swagger API

Supported Features: Additional Properties, Templates

Prerequisites: None

General Walkthrough

Leveling Schema Breakdown

A Leveling Schema defines an ordered set of Tiers that users can progress along. How that progress is measured is determined by the app but games played, games won or a more involved experience point calculation are all reasonable examples. They also support templates and additional properties on both the schema and on each tier within, which makes their details much more flexible (see Additional Properties and Templates).

An admin first creates a leveling schema through the the Admin Panel under Gamification > Levels. They can set a name, description and add any additional details, images, or other data they want. They can also select to "Use an existing trigger" to automatically create a basic Rule Engine Rule to award progress based on an existing Rule Engine Trigger to the user referenced in that trigger (one progress per event). Otherwise, progress will only be awarded by direct api calls or custom rules.

The admin also defines the list of Tiers within the leveling schema. These correspond to "levels" in a role playing game analogy, though one can use whatever terminology fits their needs. Each tier has a name and a required progress which indicates how much progress on the leveling schema the user needs before unlocking that tier. Users are generally considered to be on the tier with the highest required progress that the have reached (the tier list will reorganize by required progress if a later tier created has a lower requirement).

The leveling schema model and endpoints for leveling schema retrieval and management are described in the REST API documentation.

Basic Examples

Creating a Leveling Schema

API Documentation

POST [YOUR_URL]/leveling

request body:

{
  "name": "Return Visitor",
  "description": "Tracks users returning to the site repeatedly",
  "tiers": [
    {
      "name": "First Timer",
      "required_progress": 1
    },
    {
      "name": "Tenth Timer",
      "required_progress": 10
    },
    {
      "name": "Obsessed",
      "required_progress": 100
    }
  ],
  "trigger_event_name": "user_login"
}

response:

{
    "name": "Return Visitor",
    "description": "Tracks users returning to the site repeatedly",
    "trigger_event_name": "user_login",
    "additional_properties": {},
    "tiers": [
        {
            "name": "First Timer",
            "required_progress": 1,
            "additional_properties": {}
        },
        {
            "name": "Tenth Timer",
            "required_progress": 10,
            "additional_properties": {}
        },
        {
            "name": "Obsessed",
            "required_progress": 100,
            "additional_properties": {}
        }
    ],
    "tier_names": [
        "First Timer",
        "Tenth Timer",
        "Obsessed"
    ],
    "created_date": 1519141002,
    "updated_date": 1519141002
}

Please see our CRUD guide (create, read, update, delete) guide if you have further questions about general resource management with the REST API.

Incrementing User Progress

When the user progress towards the schema, a call can be made to add progress. Negative values can be used to remove progress and there is another endpoint to directly set the current progress total (tiers already earned are not lost). Note that this specific example, which increments progress towards a schema which is awarded based on the user_login trigger, is presumably unneeded as progress will be given automatically when the user retrieves an oauth token.

API Documentation

POST [YOUR_URL]/users/1/leveling/Return Visitor/progress

request body:

{
  "value": 1
}

Viewing User Levels

Get the list of leveling schemas a user has and/or has made progress towards. You can also retrieve the progress in a specific schema for a user with another endpoint.

API Documentation

GET [YOUR_URL]/users/1/leveling?page1&size=10

response:

{
    "content": [
        {
            "user_id": 1,
            "level_name": "Return Visitor",
            "progress": 2,
            "tier_names": [
                "First Timer"
            ],
            "last_tier_name": "First Timer",
            "last_tier_progress": 1,
            "next_tier_name": "Tenth Timer",
            "next_tier_progress": 10
        }
    ],
    "last": true,
    "total_elements": 1,
    "total_pages": 1,
    "first": true,
    "sort": null,
    "number_of_elements": 1,
    "size": 10,
    "number": 0
}