The badgeManager object is an API for getting and awarding badges and progress on badges.
A badgeManager object can be created by calling TurbulenzServices.createBadgeManager. The badgeManager is ready immediately.
Required scripts
The badgeManager object requires:
/*{{ javascript("jslib/utilities.js") }}*/
/*{{ javascript("jslib/services/badgemanager.js") }}*/
/*{{ javascript("jslib/services/turbulenzbridge.js") }}*/
/*{{ javascript("jslib/services/turbulenzservices.js") }}*/
How Badges work
Badges should be an essential part of your game and you should use them to encourage your users as they progress through your game. A game can define multiple badges.
The SDK offers a very flexible badge system that allows you to award badges in many different ways.
Badges you assign in your game are immediately displayed on the Turbulenz Gamesite (as a ‘Toast’ message or in the ‘Fold’) and can be seen on the player’s and game’s feeds.
There are two shapes for in-game badges, circle and diamond, but there can be only one diamond badge per game. The diamond badge is meant to be the most valuable badge of the game.
Your game can define a badge progress on each badge. You can even define hidden badges, that are made visible once they have been awarded.
The badge system is made up of two components, badges and userbadges.
Badges
Badges carry the meta information about a badge and can be queried with listBadges. Each specified badge mainly contains the following information:
- title and description of the badge
- key to reference a badge from your game
- visibility flag, specifying if the badge is hidden
Userbadges
Userbadges carry the information specific to the current user (like their current progress).
When a badge is awarded to a user there are two options, the badge can be awarded:
- as a whole using awardUserBadge
- progressively using updateUserBadgeProgress
Userbadges can be listed with listUserBadges.
Badge progress must be numerical. There is no upper limit to a value that a badge progress can have, however the developer has to specify a total value for progressively earned badges. In this case the badge is considered to be ‘awarded’ in full as soon as the total is achieved (e.g. 50/50).
Security
Security is important to make sure that players cannot cheat by altering the requests and responses that your game makes to our API.
All POSTs to the Badges API are expected to be protected. This means that any POST requests made must be encrypted and signed. When using the BadgeManager this is handled automatically.
However, the GET requests to the Badges API are not encrypted or signed. This means that the responses that you get from the listBadges and listUserBadges requests cannot be trusted and should only be displayed and not used internally. You should not use the results of these requests to track a player’s badge progress, instead you should track the player’s badge progress using the UserDataManager. For more information see the example in Turbulenz Services Security.
Limitations
As the progress of badges might change frequently, to avoid overloading the service, badges should not be updated for each increment. It is preferable to update these badges at a less frequent interval (e.g. every 1-10 minutes) possibly at the same time as saving your game.
Defining your game’s badges
Badges are defined with a badges.yaml file located in your games folder.
Here is an example file:
- key: 'cropmaster'
title: 'Cropmaster'
predescription: 'Harvest 10 crops in a month'
description: 'Harvested 10 crops in a month'
points: 20
total: 10
shape: 'circle'
imageresource:
icon: 'img/badges/cropmaster.png'
border-color: '#2299e3'
- key: 'seedmeister'
title: 'Seedmeister'
description: 'Planted 1000 crops in a month'
points: 100
total: 1000
shape: 'diamond'
visible: false
imageresource:
icon: 'img/badges/seedmeister.png'
border-color: '#00000'
Badges are sorted the way you define them in your YAML file. The YAML file is a dictionary of badge definitions. Each key in the dictionary is a badge key which is used as a reference to the badge for the badgeManager API calls.
Keys in this system are restricted to alphanumeric characters separated by either hyphens or dots.
Each badge definition contains:
The badges.yaml file should sit in the game directory and must be added to the deploy files of your game.
Manually removing user badges
You can find the user badges in devserver/localdata/userbadges/{game-slug}.yaml. To remove all users’ badges for a game, remove the devserver/localdata/userbadges/{game-slug}.yaml file.
Listing your badges:
var badgeListCallback = function badgeListCallbackFn(badges)
{
//do something here with your badges
var badgesLength = badges.length;
for (var i = 0; i < badgesLength; i += 1)
{
var badge = badges[i];
document.write(badge.title + ': gives you ' + badge.points + ' points and has a total score of ' + badge.total + '\n');
}
};
badgeManager.listBadges(badgeListCallback, errorCallBackFn);
Awarding a badge:
var badgeAddCallback = function badgeAddCallbackFn(userbadge)
{
//current is the current progress out of the badge total
document.write(userbadge.badge_key + ':' + userbadge.current + ':' + userbadge.username + '\n');
};
badgeManager.awardUserBadge('cropmaster', badgeAddCallback, errorCallBackFn);
Updating progress on a badge:
var badgeAddCallback = function badgeAddCallbackFn(userbadge)
{
document.write(userbadge.badge_key + ':' + userbadge.current + ':' + userbadge.username + '\n');
};
badgeManager.updateUserBadgeProgress('cropmaster', 20, badgeAddCallback, errorCallBackFn);
Listing badges for the current user:
var userbadgeListCallback = function userbadgeListCallbackFn(userbadges)
{
for (var i in userbadges)
{
if (userbadges.hasOwnProperty(i))
{
document.write(userbadges[i].username + ' owns ' + userbadges[i].badge_key + ' and the current progress is ' + userbadges[i].current + ' points\n');
}
}
};
Summary
Get a list of all badges.
Syntax
function callbackFn(badges) {}
badgeManager.listBadges(callbackFn, errorCallbackFn);
errorCallbackFn (Optional)
The callback is called with a badges array with the following format:
[
{
key: 'cropmaster',
title: 'Cropmaster',
predescription: 'Harvest 10 crops in a month',
description: 'Harvested 10 crops in a month',
points: 20,
total: 10,
visible: true,
shape: 'circle',
images: {
img32: 'https://...',
img48: 'https://...',
img256: 'https://...'
},
sortOrder: 0
},
{
key: 'seedmeister',
title: 'Seedmeister',
predescription: null,
description: 'Planted 1000 crops in a month',
points: 100,
total: 1000,
visible: false,
shape: 'diamond',
images: {
img32: 'https://...',
img48: 'https://...',
img256: 'https://...'
},
sortOrder: 1
},
...
]
Summary
Award a badge to a player.
Note
This is an encrypted API call
Syntax
function callbackFn(userBadge) {}
badgeManager.awardUserBadge(key, callbackFn, errorCallbackFn);
errorCallbackFn (Optional)
The callback is called with a userbadge with the following format:
Summary
Update the progress of a badge on a player.
Note
This is an encrypted API call
Syntax
function callbackFn(userBadge) {}
badgeManager.updateUserBadgeProgress(key, currentProgress, callbackFn, errorCallbackFn);
The callback is called with a userbadges with the following format:
Summary
List the badges for a player.
Syntax
function callbackFn(userBadge) {}
badgeManager.listUserBadges(callbackFn, errorCallbackFn);
The callback is called with a userbadges array of objects with the following format:
Summary
The ServiceRequester object for the badges service.
Syntax
var serviceRequester = badgeManager.service;
If no error callback is given then the TurbulenzServices.createbadgeManager errorCallbackFn is used.
Summary
A JavaScript function. Returns an error message and its HTTP status.
Syntax
function errorCallbackFn(errorMsg, httpStatus, calledByFn, calledByParams) {}