Last Updated: 9/22/2021, 7:52:24 AM

# Achievements

# Overview

Achievements are a tool developers can use to increase player engagement with their game. Recognizing players’ progress in your game and rewarding them with items or new characters not only fosters deeper enjoyment of your game but brand loyalty as well. There are two main types of achievements: incremental and non-incremental. Both of these types are explained below.

# Incremental Achievements

Incremental achievements work in conjunction with our Statistics service. When a player’s stats are updated, the Achievement service checks if the conditions for any incremental achievements have been met. If the conditions for an achievement have been met the achievement will be unlocked. Here are a couple examples of incremental achievements:

  • Collect 10,000 gold In order to unlock packs of bullets, a player must collect 10,000 gold.
  • Collect 100 items To unlock the Collector trait, a player must collect 100 items.

# Non-Incremental Achievements

Non-incremental achievements don’t require a goal value to be hit, and as such do not need to be integrated with the Statistics service. Here are some examples of non-incremental achievements:

  • Play your first game. To unlock a bundle of weapons, a player must play the game.
  • Kill 25 thieves in a single game. To earn their first medal, players must kill 25 thieves in a single game.

# Prerequisites

You’ll need the statistics code you created earlier when you fill in the configuration form.

# Permissions

Permissions are used to grant access to specific resources within our services. Make sure your account has the following permissions before you attempt to manage achievements in the Admin Portal. For a full list of permissions that impact achievements management, see the Achievements tab of the permissions reference.

Usage Resource Action
Create New Achievement ADMIN:NAMESPACE:{namespace}:ACHIEVEMENT Create
Export Achievement Configuration ADMIN:NAMESPACE:{namespace}:ACHIEVEMENT Read
Import Achievement Configuration ADMIN:NAMESPACE:{namespace}:ACHIEVEMENT Update
Query All Achievements ADMIN:NAMESPACE:{namespace}:ACHIEVEMENT Read
Get an Achievement ADMIN:NAMESPACE:{namespace}:ACHIEVEMENT Read
Update an Achievement ADMIN:NAMESPACE:{namespace}:ACHIEVEMENT Update
Delete an Achievement ADMIN:NAMESPACE:{namespace}:ACHIEVEMENT Update
Update Achievements List Order ADMIN:NAMESPACE:{namespace}:ACHIEVEMENT Update
Query User Achievements Include Achieved and In-progress Achievement ADMIN:NAMESPACE:{namespace}:USER:{userId}:ACHIEVEMENT Read
Unlock an Achievement NAMESPACE:{namespace}:USER:{userId}:ACHIEVEMENT Update

Permissions work slightly differently depending on whether they are assigned to IAM Clients or Roles assigned to users. For more information, read the Authentication and Authorization documentation.

# Managing Achievements in the Admin Portal

# Create a New Achievement Configuration

You’ll need the statistics code you created earlier when you fill in the configuration form.

  1. On the Achievements page of the Admin Portal, click the Add Configuration button.

achievement

  1. Once the form appears, fill in the appropriate fields.

achievement

  • Input the Code of the achievement with an appropriate format e.g. kill-enemies-achievement.
  • Input the Default Name of the achievement with a readable string. This will be the public facing name.
  • Input the Default Description of the achievement. This description is also public facing.
  • Choose if you want the achievement to be Hidden or not. Hidden achievements are not shown when they are still locked, but will appear once they’re unlocked.
  • Select Incremental for an incremental achievement, or leave the checkbox unselected for a non-incremental achievement..
  • For incremental achievements, input the StatCode with the statistics code for the relevant statistic. You can leave this field empty if you’re creating a non-incremental achievement.
  • For incremental achievements, input the Goal Value. Note that the goal value should not exceed the max value defined in the Statistic - Configuration. You can leave this field empty if you’re creating a non-incremental achievement.
  • Input the Tag field with contextual information related to the achievement.
  • Select an image for the Locked Icon. This image will display for players who do not have this achievement yet.
  • Select an image to be displayed when the achievement is Unlocked.
  1. Click Add. Your new configuration will be added to the list.

achievement

# Export Achievement Configurations

You can export your achievement configurations in JSON format by following the steps below.

  1. In the Achievements menu of the Admin Portal, open the dropdown menu next to the Add Configuration button and choose Export Configuration.

achievement

  1. The download will be started. Once it’s finished, open the JSON file to see your achievement configs.

# Import an Achievement Configuration

  1. In the Achievements menu of the Admin Portal, open the dropdown menu next to the Add Configuration button and choose Import Configuration.

achievement

  1. The Import Configuration form will appear.

achievement

  • Choose a File to Import. The file should be in JSON format.

  • Select the Import Method.

  • Choose Replace if you want to replace an old config with a new one. The new config must have the same key as the config you want to replace. If you have multiple configs in your file, any configs with unique keys will also be imported.

  • Choose Leave Out if you want to add a new config without replacing any old configs. Using this method, any configs in your JSON file whose keys match existing configs will not be imported. Only configs with unique keys will be imported.

Click Import.

  1. Confirm the import configuration by typing IMPORT in the pop-up form below.

achievement

# Implementing Achievements using the SDK

# Unlock an Achievement

There are two ways to unlock a player’s achievement: either from Game Client or from the Game Dedicated Server.

# Unlock an Achievement from the Game Client

Note that this function can only be used for non-incremental achievements that do not affect gameplay. For example, the first time going to the gallery, first time inviting a friend, etc.

# Unlock an Achievement from the Dedicated Server

Unlocking an achievement from the server is usually done after a match is completed.

# Achievements Query

# Get a Single Achievement

You can use this function to retrieve achievement info, such as the achievement name, description, goalValue, etc.

# Query All Achievements

You can use this function to retrieve a list of all achievements in the related namespace.

# Query a Player’s Achievement

You can use this function to query a player’s unlocked and in-progress achievements.

# Managing Achievements using API

You can also use our API endpoints to manage players’ achievements.

# Create a New Achievement Configuration

You can create a new achievement configuration using the API. To do so, follow the steps below:

  1. Use the Create New Achievement: POST - /achievement​/v1​/admin​/namespaces​/{namespace}​/achievements endpoint.
  2. Input the Namespace where the configuration will belong.
  3. Fill out the Request Body:
  • Input the Achievement Code to identify the achievement.

  • Input the Default Language of the achievement which will be the achievement name & description language.

  • Input the Default Description of the achievement. This description is also public-facing.

  • For incremental achievements, input the Goal Value. Goal Value is a statistic value that’s required to unlock the achievement. Note that the goal value should not exceed the max value defined in the Statistic Configuration. You can leave this field empty if you’re creating a non-incremental achievement.

  • Choose if you want the achievement to be Hidden or not. Hidden achievements are not shown when they are still locked, but will appear once they’re unlocked.

  • Set the Incremental to true for an incremental achievement, or false for a non-incremental achievement.

  • In the Locked Icon fields

  • Specify the image in the Slug field, it can be an image name or something to define the achievement icon.

  • Input the URL of the image.

  • Input the name of the Achievement Configuration

  • For incremental achievements, input the StatCode with the statistics code for the relevant statistic. You can leave this field empty if you’re creating a non-incremental achievement.

  • Select an image to be displayed when the achievement is Unlocked.

  • Specify the image in the Slug field, it can be an image name or something to define the achievement icon.

  • Input the URL of the image.

Upon a successful request, the achievement configuration will be created. Here is the response example of the successful request:

# Query All Achievements

You can query all achievement configuration using the API. To do so, follow the steps below:

  1. Use the Query Achievement: GET - /achievement/v1/admin/namespaces/{namespace}/achievements endpoint.
  2. Input the Namespace where you want to retrieve the configuration.
  3. Input the Limit of the displayed data. The default value is 10.
  4. Define how you want to sort the data in the sortBy field. The default value is listOrder:asc. Here’s the available value.
Sort by Description
listOrder Sort by list number. The available value is.
  • listOrder:asc for ascending
  • listOrder:desc for descending
createdAt Sort by the created date of the configuration. The available value is.
  • createdAt:asc for ascending
  • createdAt:desc for descending
updatedAt Sort by the updated date of the configuration. The available value is.
  • updatedAt:asc for ascending
  • updatedAt:desc for descending
  1. Input the offset with the start position of the data in the paginated result. The default value is 0.

Upon a successful request, the achievement configuration will be retrieved. Here is the response example of the successful request:

# Get a Single Achievement

You can query all achievement configuration using the API. To do so, follow the steps below:

  1. Use the Get an Achievement: GET - /achievement/v1/admin/namespaces/{namespace}/achievements/{achievementCode}
  2. Input the Namespace with the game namespace.
  3. Input the Achievement Code of the configuration.

Upon a successful request, the achievement configuration will be retrieved. Here is the response example of the successful request:

# Query a Player’s Achievement

You can query a player’s achievement configuration using the API. To do so, follow the steps below:

  1. Use the Get an Achievement: GET - /achievement/v1/admin/namespaces/{namespace}/achievements/{achievementCode}
  2. Input the User ID of the players you want to retrieve the achievement.
  3. To display the data in pagination, fill in the following fields
  • Input the offset with the start position of the data in the paginated result. The default value is 0.
  • Input the Limit of the displayed data. The default value is 10.
  1. Set the preferUnlocked value to true if you only want to display achieved achievement and set it to false for all achievement.

Upon a successful request, the player achievement will be retrieved. Here is the response example of the successful request:

# Import an Achievement Configuration

You can import achievement configuration using the API. To do so, follow the steps below:

  1. Use the Import Achievements from File: POST - /achievement/v1/admin/namespaces/{namespace}/achievements/import endpoint.
  2. Input the Game Namespace where the configuration belongs.
  3. Choose the file to be imported.
  4. Select the import Strategy. Here is the available strategy. The default value is leaveOut.
  • leaveOut. If configuration with same key exist, the existing will be used and imported one will be ignored
  • replace. if configuration with same key exist, the imported channel will be used and existing one will be removed

Upon a successful request, the achievement configuration will be imported. Here is the response example of the successful request:

# Export an Achievement Configuration

You can import achievement configuration using the API. To do so, follow the steps below:

  1. Use the Export Achievements Configuration into a JSON File: GET - /achievement/v1/admin/namespaces/{namespace}/achievements/export endpoint.
  2. Input the Game Namespace where the configuration belongs.

Upon a successful request, the achievement configuration will be exported in a JSON file. Here is the response example of the successful request:

# Unlock an Achievement

You can import achievement configuration using the API. To do so, follow the steps below:

  1. Use the Unlock an Achievement: PUT - /achievement/v1/admin/namespaces/{namespace}/users/{userId}/achievements/{achievementCode}/unlock endpoint.
  2. Input the Game Namespace where the configuration belongs.
  3. Input the User ID of the players you want to unlock the achievement.
  4. Input the Achievement Code.

Upon a successful request, the achievement will be unlocked to the players. The success response code is 204 with no content

  • Once you have achievements in place, you can create Leaderboards.