Comment on page
Achievements
Integration Guide
The
AchievementsModule
allows to give the user different rewards for making progress. The first things you'll need to decide are when you want to reward the user and what should be given as a reward.Currently, the achievements support 3 types of user rewards:
- 1.Virtual Items rewards - the virtual items are added to the user's inventory
- 2.Currency Coins rewards - the currency coins are added to the user's data. It is not possible to give the special "rgn-coin" as a currency reward here.
- 3.Progression rewards - If you want to track user progress. You can use custom progression data types and store those in the user's data. When the achievement is completed and the progression rewards are given, it will increment the user's progression values accordingly. The progression values should be numbers. To retrieve the progression data you need to use the
GameProgressModule:
GetUserProgressionDataAsync()
method.
You can create new achievements by using the developer dashboard or by reaching out to the Ready team.
using System.Collections.Generic;
using RGN.Modules.Achievement;
using RGN.Utility;
namespace SomeNamespace
{
internal sealed class GetAchievements
{
public async void GetAchievementsAsync()
{
List<AchievementData> achievementsData =
await AchievementsModule.I.GetForCurrentAppAsync(10);
for (int i = 0; i < achievementsData.Count; ++i)
{
var achievement = achievementsData[i];
UnityEngine.Debug.Log(achievement.name);
UnityEngine.Debug.Log(achievement.description);
}
}
}
}
The
GetAsync()
method supports pagination. You can provide limit
and startAfter
parameters to partially retrieve the achievements. The startAfter
parameter is an optional parameter representing an achievement id after which to start retrieving the achievements. The default is an empty string.Returns list of achievements created for the current application.
id
(string) - unique identifier of the achievement, is used to triggerappIds
(list of strings) - list of application ids where this achievement is usedname
(string) - achievement name. This value can be null or emptydescription
(string) - achievement description. This value can be null or emptysetBy
(string) - defines who can trigger or claim the achievement. Possible values:client
orserver
. Client means you can trigger or claim the achievement directly from Unity SDK. When theserver
setting is used, the trigger or claim function will work only when triggered from the server side. For example when achievements are used in matchmaking. In case the achievement hasserver
setBy
theClaimAsync()
orTriggerAsync()
methods will throw an exception.isClaimable
(bool) - determines if the user needs to claim the achievement rewards after the achievement is completed.valueToReach
(int) - value which should be reached by the user to complete the achievement. You can provide optional parameters to theTriggerAsync()
method to increment the user progress.completedAchievementsToUnlock
(list of strings) - list of other achievement ids that need to be completed before this achievement is completed. The rewards will be not given for achievement A if it has in thecompletedAchievementsToUnlock
achievement B and B is not yet completed.repeatable
(bool) - indicates whether the achievement can be completed multiple times. It means if this value istrue
then the rewards are given to the user every time the achievement is triggered or claimed. In case it isfalse
the rewards are given only the first time. All subsequent calls to the achievements trigger function will not give any user rewardsrepeatNoMoreOftenThanCron
(string) - this string specifies how often the achievement can repeat. This parameter is used only in case the achievement isrepeatable
. The parameter is a cron string. You can use this website to specify the string: https://crontab.guru/ This parameter is useful to create weekly or daily achievements.startTime
(long) - time in milliseconds since midnight, January 1, 1970 UTC when the achievement start to be active for users.endTime
(long) - time in milliseconds since midnight, January 1, 1970 UTC when the achievement will be inactivated.resetTimeLimitEvery
(string) - this string specifies how often and when thestartTime
andendTime
should reset. The parameter is a cron string. You can use this website to specify the string: https://crontab.guru/ rewards
(list ofAchievementReward
objects) - this parameter specifies the rewards that will be given to the user when the achievement is triggered or claimed. More info for theAchievementReward
structure below.createdAt
(long) - timestamp in milliseconds since midnight, January 1, 1970 UTC when the achievement was created. You can use theRGN.Utility.DateTimeUtility
class to convert the value to DateTime or string.updatedAt
(long) - timestamp in milliseconds since midnight, January 1, 1970 UTC when the achiement was last time updated. You can use theRGN.Utility.DateTimeUtility
class to convert the value to DateTime or string.createdBy
(string) - creator user id.updatedBy
(string) - id of the user who last time updated the achievement data.
type
(string) - The type of reward this achievement offers. This could be "virtualItem
", "currency
", or "progression
" to match the different types of reward systems available.appIds
(array of strings) - The list of application IDs for which this achievement reward is applicable. This allows rewards to be scoped to specific applications within a developer's portfolio.name
(string) - The name of the reward. This could be the id of the virtual item, currency name, or progression id.quantity
(int) - The quantity of the reward that will be given to the user upon completing the achievement. For "virtualItem
" and "currency
", it represents the number of items or coins rewarded. For "progression
", it represents the increment value for the user's progression.
In order to complete an achievement you can call the following function by passing the achievement's unique id (string) as a parameter:
using RGN.Modules.Achievement;
using UnityEngine;
namespace SomeNamespace
{
internal sealed class TriggerAchievement
{
public async void CompleteAchievementAsync(string achievementId)
{
await AchievementsModule.I.TriggerByIdAsync(achievementId);
Debug.Log(achievementId);
}
}
}
In case the achievement is not repeatable and was already triggered for the current user this call will succeed, but the rewards will not be given again. The same applies to repeatable achievements but with the
repeatNoMoreOftenThanCron
setting. You can for example create a daily reward achievement that will reward the user on every login, but no more often than once a day. In this case, you need to set
repeatable
flag to true
and set the repeatNoMoreOftenThanCron
string to "0 0 * * *".In case the achievement
valueToReach
is more than 1, the trigger function will increment the current user progress value by 1. You can also provide custom progress value to the function:using RGN.Modules.Achievement;
using UnityEngine;
namespace SomeNamespace
{
internal sealed class TriggerAchievementWithProgress
{
public async void TriggerAchievementWithProgressAsync(string achievementId)
{
// Triggers the achievement for current logged in user:
// The user progress value will be incremented by 42 after the call
await AchievementsModule.I.TriggerByIdAsync(achievementId, 42);
Debug.Log(achievementId);
}
}
}
Instead of using id in the trigger function, you can also use request name, for example:
using RGN.Modules.Achievement;
using UnityEngine;
namespace SomeNamespace
{
internal sealed class TriggerAchievementByRequestName
{
public async void CompleteAchievementAsync(string requestName)
{
await AchievementsModule.I.TriggerByRequestNameAsync(requestName);
Debug.Log(requestName);
}
}
}
In case the
isClaimable
flag for achievement is true, the rewards will not be given automatically to the user when the achievement is triggered and completed. The user needs to claim the achievement.using RGN.Modules.Achievement;
using UnityEngine;
namespace SomeNamespace
{
internal sealed class ClaimAchievement
{
public async void ClaimAchievementAsync(string achievementId)
{
await AchievementsModule.I.ClaimByIdAsync(achievementId);
Debug.Log(achievementId);
}
}
}
Same as for trigger function for claim function you can use request name to determine which achievement to claim:
using RGN.Modules.Achievement;
using UnityEngine;
namespace SomeNamespace
{
internal sealed class ClaimAchievementByRequestName
{
public async void ClaimAchievementAsync(string requestName)
{
await AchievementsModule.I.ClaimByRequestNameAsync(requestName);
Debug.Log(requestName);
}
}
}
When the user completes an achievement (the rewards are given to the user) the information is stored in the backend. You can get all completed achievements for the currently authorized user, or for other users in case you provide the
userId
parameter.using System.Collections.Generic;
using RGN.Modules.Achievement;
using UnityEngine;
namespace SomeNamespace
{
internal sealed class GetUserAchievements
{
public async void GetUserAchievementsAsync()
{
List<UserAchievement> userAchievements =
await AchievementsModule.I.GetUserAchievementsAsync();
for (int i = 0; i < userAchievements.Count; ++i)
{
UserAchievement achievement = userAchievements[i];
Debug.Log(achievement.id);
for (int j = 0; j < achievement.history.Count; ++j)
{
Debug.Log(JsonUtility.ToJson(achievement.history[j]));
}
}
}
}
}
Each completed achievement entry contains non-empty
history
list. This list stores all times the rewards were given to the user for this achievement. For example, if the user completed "achievement_a" 3 times, then the history list will contain 3 items.You can provide the
userId
parameter to get the completed achievements for other users.The
GetUserCompletedAchievements()
method also supports pagination. You can provide the limit
and startAfter
parameters to partially retrieve the completed user achievements. The startAfter
parameter is based on the CompletedAchievement.lastCompleteTime
field.
Sometimes it is useful to request the achievements for the current app and show the user's progress for each achievement. The
GetForCurrentAppAsync()
method does not return user-related information. To retrieve the achievements list with user information you can use the GetForCurrentAppWithUserDataAsync()
using System.Collections.Generic;
using RGN.Modules.Achievement;
namespace SomeNamespace
{
internal sealed class GetAchievementsWithUserData
{
public async void GetAchievementsWithUserDataAsync()
{
List<AchievementWithUserData> achievements =
await AchievementsModule.I.GetForCurrentAppWithUserDataAsync(10);
for (int i = 0; i < achievements.Count; ++i)
{
var achievement = achievements[i];
UnityEngine.Debug.Log(achievement.name);
UnityEngine.Debug.Log(achievement.description);
UserAchievement userAchievement = achievement.GetUserAchievement();
if (userAchievement != null)
{// check for null is important
UnityEngine.Debug.Log(userAchievement.value);
UnityEngine.Debug.Log(userAchievement.valueToReach);
UnityEngine.Debug.Log(userAchievement.isClaimed);
UnityEngine.Debug.Log(userAchievement.history);
}
}
}
}
}
The
GetForCurrentAppWithUserDataAsync()
method supports pagination. You can provide limit
and startAfter
parameters to partially retrieve the achievements with user data. The startAfter
parameter is an optional parameter representing an achievement id after which to start retrieving the achievements. The default is an empty string.