Unlock player achievements using AGS SDK

Last updated on July 16, 2024

Overview

The AccelByte Gaming Services (AGS) Achievements service allows you to choose various ways to unlock user achievements depending on your game needs. Unlocking user achievements is dependent on the achievement configuration you have set up. You can only manually unlock a non-incremental achievement. For the an incremental achievement, it will be automatically unlocked once the player has already achieved the achievement goal value.

In this guide, you will learn how the Achievements service unlock process works.

Goals

• Explain how to utilize AccelByte SDK to unlock an achievement.

Prerequisites

• Access to the AGS Admin Portal.
• AccelByte Unreal, Unity, or Extend SDK, including the permissions:
  • Client ID
  • Client Secret
• Access to AccelByte Achievement API documentation.
• Access to the AccelByte Statistics API to configure the required information.

Unlock an achievement

There are two ways to unlock a player's achievement: either from the game client or from the game dedicated server.

Unlock an achievement from the game client

This unlocking process is suitable for unlocking achievements that do not affect the gameplay, such as the player's first time logging in, the player's first time inviting a friend, etc.

info

This unlocking process can only be used for non-incremental achievement configuration.

To unlock the achievement, you are required to know the achievementCode. You can use that achievement code and the following function to unlock the achievement:

Unreal

FString AchievementCode = FString("MyAchievementCode");

FRegistry::Achievement.UnlockAchievement(AchievementCode, FVoidHandler::CreateLambda([]()
{
    // Do something if UnlocKAchievement is successful
}), FErrorHandler:: CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if UnlockAchievement has an error
}));

Unity

var achievement = AccelByteSDK.GetClientRegistry().GetApi().GetAchievement();

string achievementCode = "MyAchievementCode";

achievement.UnlockAchievement(achievementCode, result =>
{
    if (result.IsError)
    {
        // Do something if UnlockAchievement has an error
        Debug.Log($"Error UnlockAchievement, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");

        return;
    }

    // Do something if UnlockAchievement is successful
});

Go Extend SDK

userAchievementsService := &achievement.UserAchievementsService{
    Client:          factory.NewAchievementClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
achievementCode := "achievementCode"
namespace := "mygame"
userId := "myuserid"
input := &user_achievements.PublicUnlockAchievementParams{
    AchievementCode: achievementCode,
    Namespace:       namespace,
    UserID:          userId,
}
err := userAchievementsService.PublicUnlockAchievementShort(input)

Python Extend SDK

import accelbyte_py_sdk.api.achievement as achievement_service
import accelbyte_py_sdk.api.achievement.models as achievement_models

result, error = achievement_service.public_unlock_achievement(
    achievement_code="MyAchievementCode",
    user_id="********************************",
)
if error:
    exit(error)

Java Extend SDK

final UserAchievements userAchievementsWrapper = new UserAchievements(sdk);

String achievementCode = "<achievement-code>";
String userId = "<user-id>";
try {
  userAchievementsWrapper.publicUnlockAchievement(PublicUnlockAchievement.builder()
        .namespace("<namespace>")
        .userId(userId)
        .achievementCode(achievementCode)
        .build());
} catch (Exception e) {
  // Do something when failed
  return;
}

C# Extend SDK

string achievementCode = "<achievement-code>";
string userId = "<user-id>";

sdk.Achievement.UserAchievements.PublicUnlockAchievementOp
    .Execute(achievementCode, sdk.Namespace, userId);

Unlock an achievement from the dedicated server

Unlocking an achievement from the server is usually done after a match is completed. To unlock an achievement from the dedicated server, you are required to have the userID of the user you want to grant the achievement and the achievementCode. You can use that information and the following function to unlock the achievement:

Unreal

FString AchievementCode = FString("MyAchievementCode");
FString UserId = FString("UserId");
    
FRegistry::ServerAchievement.UnlockAchievement(UserId, AchievementCode, FVoidHandler::CreateLambda([]()
{
    // Do something if UnlockAchievement is successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if UnlockAchievement has an error
}));

Unity

var achievement = AccelByteSDK.GetServerRegistry().GetApi().GetAchievement();

string achievementCode = "MyAchievementCode";
string userId = "UserId";

achievement.UnlockAchievement(userId, achievementCode, result =>
{
    if (result.IsError)
    {
        // Do something if UnlockAchievement has an error
        Debug.Log($"Error UnlockAchievement, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        
        return;
    }
        
    // Do something if UnlockAchievement is successful
});

Go Extend SDK

userAchievementsService := &achievement.UserAchievementsService{
    Client:          factory.NewAchievementClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}
achievementCode := "achievementCode"
namespace := "mygame"
userId := "myuserid"
input := &user_achievements.AdminUnlockAchievementParams{
    AchievementCode: achievementCode,
    Namespace:       namespace,
    UserID:          userId,
}
err := userAchievementsService.AdminUnlockAchievementShort(input)

Python Extend SDK

import accelbyte_py_sdk.api.achievement as achievement_service
import accelbyte_py_sdk.api.achievement.models as achievement_models

result, error = achievement_service.admin_unlock_achievement(
    achievement_code="MyAchievementCode",
    user_id="********************************",
)
if error:
    exit(error)

Java Extend SDK

final UserAchievements userAchievementsWrapper = new UserAchievements(sdk);

String achievementCode = "<achievement-code>";
String userId = "<user-id>";
try {
  userAchievementsWrapper.adminUnlockAchievement(AdminUnlockAchievement.builder()
    .namespace("<namespace>")
    .userId(userId)
    .achievementCode(achievementCode)
    .build());
} catch (Exception e) {
  // Do something when failed
  return;
}

C# Extend SDK

string achievementCode = "<achievement-code>";
string userId = "<user-id>";

sdk.Achievement.UserAchievements.AdminUnlockAchievementOp
    .Execute(achievementCode, sdk.Namespace, userId);