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:

Virtual Items rewards - the virtual items are added to the user's inventory
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.
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 READYgg team.

Retrieve achievement list:

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.

Response:

Returns list of achievements created for the current application.

AchievementData

id(string) - unique identifier of the achievement, is used to trigger
appIds (list of strings) - list of application ids where this achievement is used
name (string) - achievement name. This value can be null or empty
description (string) - achievement description. This value can be null or empty
setBy (string) - defines who can trigger or claim the achievement. Possible values: client or server. Client means you can trigger or claim the achievement directly from Unity SDK. When the server 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 has server setBy the ClaimAsync() or TriggerAsync() 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 the TriggerAsync() 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 the completedAchievementsToUnlock achievement B and B is not yet completed.
repeatable (bool) - indicates whether the achievement can be completed multiple times. It means if this value is true then the rewards are given to the user every time the achievement is triggered or claimed. In case it is false the rewards are given only the first time. All subsequent calls to the achievements trigger function will not give any user rewards
repeatNoMoreOftenThanCron (string) - this string specifies how often the achievement can repeat. This parameter is used only in case the achievement is repeatable. 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 the startTime and endTime should reset. The parameter is a cron string. You can use this website to specify the string: https://crontab.guru/
rewards (list of AchievementReward objects) - this parameter specifies the rewards that will be given to the user when the achievement is triggered or claimed. More info for the AchievementReward structure below.
createdAt (long) - timestamp in milliseconds since midnight, January 1, 1970 UTC when the achievement was created. You can use the RGN.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 the RGN.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.

AchievementReward

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.

Trigger achievement:

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);
        }
    }
}

Claim an achievement:

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);
        }
    }
}

Get users completed achievements:

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.

Also you can provide the withHistory parameter to get completion history for returned achievements.

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.

Get achievements for the current app with user data:

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.

PreviousInventory NextLeaderboards