![]() |
CloudBuilder
2.8.4
Making social games is easy !
|
CloudBuilder provides a platform independent way of handling achievements for your game. Note that achievements need to be defined on the backoffice before being used on the client.
This page is aimed at being a little tutorial on how to work with achievements from the CloudBuilder SDK (client). For the next steps, we will suppose that you already know how to create achievements from the backoffice. For a complete list of useful functions in the SDK, take a look at Achievements module.
Fetching the state of achievements is a function that require the customer to be logged in. In general, the status of achievements represents an association between a gamer and a game.
The call that we are going to use is ListAchievements
:
This call requires a configuration passed in the form of a CHJSON
object as usual. Read the documentation for more information on the keys that should be passed. An example is shown below, we'll create UI buttons with information about each achievement. The GUI toolkit is virtual, and you may want to implement additional features such as pagination.
If you have configured your achievements through the backoffice, you know that achievements are triggered when so-called units reach a certain value. This means that to trigger an achievement, you will increase the value of an unit. An easy way to perform that is by using the following method.
void CloudBuilder::CUserManager::EarnAchievment(const char *unit, int increment, const CHJSON *gamerData, CResultHandler *handler);
Most parameters except for the unit
can be left at their default value, which means that the unit will be incremented from one and no gamer data will be posted. The following example shows how to notify an achievement. We expect an achievement like that to have been configured in the backoffice :
The special thing here is that the name of the achievement is the same as the unit, which should be perfect for most achievements. Posting an achievement is done as follows:
Now on processing the response. The result is what you get from CloudBuilder::CUserManager::TransactionV2. That is, two nodes: balance
and achievements
. For a player who has never played before, the result should look like:
This is it for the "simple" version. Achievements provide much more powerful functionality, which you can access by separately calling CloudBuilder::CUserManager::TransactionV2 (to post the fact that an unit has changed, potentially realizing an achievement) and CloudBuilder::CUserManager::SetAchievementData to associate data with the achievement if needed.
The previous call would look like this:
Note that this time, we are making a transaction with a key value of name supersonic
, and we are storing data (SetAchievementData
) with the achievement supersonic
. Unlike the previous call to EarnAchievement
, they need not be the same. You could for instance configure an achievement named beRich
which triggers when goldCoins
reaches 100000. In that case, you would pass different strings to TransactionV2
(goldCoins
) and SetAchievementData
(beRich
).
By default, achievements use the key/value storage associated with the private domain (that is, reserved for this game). You may create achievement on different domains, in which case they refer to units posted in the corresponding domain.
Data can be associated for an user and an achievement. To store it, pass a CHJSON
as third parameter to CloudBuilder::CUserManager::EarnAchievement. Or call CloudBuilder::CUserManager::SetAchievementData as shown below. In the following case, we want to unhide an achievement that has been marked as hidden by default and not listed in the section above.
Other uses for data stored by user and achievement include storing any useful detail on how the gamer did get the score.